Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Merge with docrails. Also add a rake task to generate guides in your …

…rails application :

  rake doc:guides

The rake task will generate guides inside doc/guides directory of your application. Open index.html to browse.
  • Loading branch information...
commit a03e2b356c66ddc8809fa2b23a2a7d652f173b8b 1 parent 18542c9
@lifo lifo authored
Showing with 20,664 additions and 661 deletions.
  1. +2 −1  .gitignore
  2. +6 −6 actionpack/lib/action_view/helpers/date_helper.rb
  3. +2 −1  activerecord/lib/active_record/associations.rb
  4. +7 −1 activerecord/lib/active_record/associations/association_collection.rb
  5. +1 −0  activerecord/lib/active_record/associations/has_many_association.rb
  6. +2 −2 activesupport/lib/active_support/multibyte/chars.rb
  7. +41 −48 railties/Rakefile
  8. +0 −91 railties/doc/guides/actionview/helpers.markdown
  9. +0 −90 railties/doc/guides/actionview/partials.markdown
  10. +0 −56 railties/doc/guides/activerecord/basics.markdown
  11. +0 −55 railties/doc/guides/benchmarking_and_profiling/basics.txt
  12. +0 −22 railties/doc/guides/benchmarking_and_profiling/definitions.txt
  13. +0 −44 railties/doc/guides/benchmarking_and_profiling/preamble.txt
  14. +1,125 −0 railties/doc/guides/html/actioncontroller_basics.html
  15. +2,577 −0 railties/doc/guides/html/association_basics.html
  16. +227 −0 railties/doc/guides/html/authors.html
  17. +1,015 −0 railties/doc/guides/html/benchmarking_and_profiling.html
  18. +577 −0 railties/doc/guides/html/caching_with_rails.html
  19. +1,402 −0 railties/doc/guides/html/creating_plugins.html
  20. +1,051 −0 railties/doc/guides/html/debugging_rails_applications.html
  21. +901 −0 railties/doc/guides/html/finders.html
  22. +570 −0 railties/doc/guides/html/form_helpers.html
  23. +1,895 −0 railties/doc/guides/html/getting_started_with_rails.html
  24. +381 −0 railties/doc/guides/html/index.html
  25. +1,199 −0 railties/doc/guides/html/layouts_and_rendering.html
  26. +921 −0 railties/doc/guides/html/migrations.html
  27. +2,183 −0 railties/doc/guides/html/routing_outside_in.html
  28. +1,280 −0 railties/doc/guides/html/security.html
  29. +1,751 −0 railties/doc/guides/html/testing_rails_applications.html
  30. 0  railties/doc/guides/{actioncontroller → source/actioncontroller_basics}/cookies.txt
  31. 0  railties/doc/guides/{actioncontroller → source/actioncontroller_basics}/filters.txt
  32. 0  railties/doc/guides/{actioncontroller → source/actioncontroller_basics}/http_auth.txt
  33. 0  railties/doc/guides/{actioncontroller/actioncontroller.txt → source/actioncontroller_basics/index.txt}
  34. 0  railties/doc/guides/{actioncontroller → source/actioncontroller_basics}/introduction.txt
  35. 0  railties/doc/guides/{actioncontroller → source/actioncontroller_basics}/methods.txt
  36. 0  railties/doc/guides/{actioncontroller → source/actioncontroller_basics}/parameter_filtering.txt
  37. 0  railties/doc/guides/{actioncontroller → source/actioncontroller_basics}/params.txt
  38. 0  railties/doc/guides/{actioncontroller → source/actioncontroller_basics}/request_response_objects.txt
  39. 0  railties/doc/guides/{actioncontroller → source/actioncontroller_basics}/rescue.txt
  40. 0  railties/doc/guides/{actioncontroller → source/actioncontroller_basics}/session.txt
  41. 0  railties/doc/guides/{actioncontroller → source/actioncontroller_basics}/streaming.txt
  42. 0  railties/doc/guides/{actioncontroller → source/actioncontroller_basics}/verification.txt
  43. +120 −0 railties/doc/guides/source/active_record_basics.txt
  44. +2 −1  railties/doc/guides/{activerecord → source}/association_basics.txt
  45. 0  railties/doc/guides/{ → source}/authors.txt
  46. +0 −9 railties/doc/guides/{ → source}/benchmarking_and_profiling/appendix.txt
  47. 0  railties/doc/guides/{ → source}/benchmarking_and_profiling/digging_deeper.txt
  48. 0  railties/doc/guides/{ → source}/benchmarking_and_profiling/edge_rails_features.txt
  49. 0  railties/doc/guides/{ → source}/benchmarking_and_profiling/examples/graph.html
  50. 0  railties/doc/guides/{ → source}/benchmarking_and_profiling/gameplan.txt
  51. 0  railties/doc/guides/{ → source}/benchmarking_and_profiling/images/kgraph.png.html
  52. 0  railties/doc/guides/{ → source}/benchmarking_and_profiling/images/klist.png.html
  53. +241 −0 railties/doc/guides/source/benchmarking_and_profiling/index.txt
  54. 0  railties/doc/guides/{ → source}/benchmarking_and_profiling/rubyprof.txt
  55. 0  railties/doc/guides/{ → source}/benchmarking_and_profiling/statistics.txt
  56. 0  railties/doc/guides/{caching → source}/caching_with_rails.txt
  57. 0  railties/doc/guides/{ → source}/creating_plugins/acts_as_yaffle.txt
  58. 0  railties/doc/guides/{ → source}/creating_plugins/appendix.txt
  59. 0  railties/doc/guides/{ → source}/creating_plugins/basics.markdown
  60. 0  railties/doc/guides/{ → source}/creating_plugins/custom_generator.txt
  61. 0  railties/doc/guides/{ → source}/creating_plugins/custom_route.txt
  62. 0  railties/doc/guides/{creating_plugins/creating_plugins.txt → source/creating_plugins/index.txt}
  63. 0  railties/doc/guides/{ → source}/creating_plugins/migration_generator.txt
  64. 0  railties/doc/guides/{ → source}/creating_plugins/odds_and_ends.txt
  65. 0  railties/doc/guides/{ → source}/creating_plugins/preparation.txt
  66. 0  railties/doc/guides/{ → source}/creating_plugins/string_to_squawk.txt
  67. 0  railties/doc/guides/{ → source}/creating_plugins/view_helper.txt
  68. +106 −86 railties/doc/guides/{debugging → source}/debugging_rails_applications.txt
  69. +37 −5 railties/doc/guides/{activerecord → source}/finders.txt
  70. 0  railties/doc/guides/{forms → source}/form_helpers.txt
  71. +31 −21 railties/doc/guides/{getting_started_with_rails → source}/getting_started_with_rails.txt
  72. 0  railties/doc/guides/{ → source}/icons/README
  73. 0  railties/doc/guides/{ → source}/icons/callouts/1.png
  74. 0  railties/doc/guides/{ → source}/icons/callouts/10.png
  75. 0  railties/doc/guides/{ → source}/icons/callouts/11.png
  76. 0  railties/doc/guides/{ → source}/icons/callouts/12.png
  77. 0  railties/doc/guides/{ → source}/icons/callouts/13.png
  78. 0  railties/doc/guides/{ → source}/icons/callouts/14.png
  79. 0  railties/doc/guides/{ → source}/icons/callouts/15.png
  80. 0  railties/doc/guides/{ → source}/icons/callouts/2.png
  81. 0  railties/doc/guides/{ → source}/icons/callouts/3.png
  82. 0  railties/doc/guides/{ → source}/icons/callouts/4.png
  83. 0  railties/doc/guides/{ → source}/icons/callouts/5.png
  84. 0  railties/doc/guides/{ → source}/icons/callouts/6.png
  85. 0  railties/doc/guides/{ → source}/icons/callouts/7.png
  86. 0  railties/doc/guides/{ → source}/icons/callouts/8.png
  87. 0  railties/doc/guides/{ → source}/icons/callouts/9.png
  88. 0  railties/doc/guides/{ → source}/icons/caution.png
  89. 0  railties/doc/guides/{ → source}/icons/example.png
  90. 0  railties/doc/guides/{ → source}/icons/home.png
  91. 0  railties/doc/guides/{ → source}/icons/important.png
  92. 0  railties/doc/guides/{ → source}/icons/next.png
  93. 0  railties/doc/guides/{ → source}/icons/note.png
  94. 0  railties/doc/guides/{ → source}/icons/prev.png
  95. 0  railties/doc/guides/{ → source}/icons/tip.png
  96. 0  railties/doc/guides/{ → source}/icons/up.png
  97. 0  railties/doc/guides/{ → source}/icons/warning.png
  98. 0  railties/doc/guides/{activerecord → source}/images/belongs_to.png
  99. BIN  railties/doc/guides/source/images/bullet.gif
  100. 0  railties/doc/guides/{securing_rails_applications → source}/images/csrf.png
  101. 0  railties/doc/guides/{activerecord → source}/images/habtm.png
  102. 0  railties/doc/guides/{activerecord → source}/images/has_many.png
  103. 0  railties/doc/guides/{activerecord → source}/images/has_many_through.png
  104. 0  railties/doc/guides/{activerecord → source}/images/has_one.png
  105. 0  railties/doc/guides/{activerecord → source}/images/has_one_through.png
  106. BIN  railties/doc/guides/source/images/header_backdrop.png
  107. 0  railties/doc/guides/{activerecord → source}/images/polymorphic.png
  108. BIN  railties/doc/guides/source/images/rails_logo_remix.gif
  109. BIN  railties/doc/guides/source/images/ruby_on_rails_by_mike_rundle2.gif
  110. 0  railties/doc/guides/{securing_rails_applications → source}/images/session_fixation.png
  111. +16 −14 railties/doc/guides/{ → source}/index.txt
  112. +54 −1 railties/doc/guides/{actionview → source}/layouts_and_rendering.txt
  113. 0  railties/doc/guides/{ → source}/migrations/anatomy_of_a_migration.txt
  114. 0  railties/doc/guides/{ → source}/migrations/changelog.txt
  115. 0  railties/doc/guides/{ → source}/migrations/creating_a_migration.txt
  116. 0  railties/doc/guides/{ → source}/migrations/foreign_keys.txt
  117. 0  railties/doc/guides/{migrations/migrations.txt → source/migrations/index.txt}
  118. 0  railties/doc/guides/{ → source}/migrations/rakeing_around.txt
  119. 0  railties/doc/guides/{ → source}/migrations/scheming.txt
  120. 0  railties/doc/guides/{ → source}/migrations/using_models_in_migrations.txt
  121. 0  railties/doc/guides/{ → source}/migrations/writing_a_migration.txt
  122. +27 −0 railties/doc/guides/{routing → source}/routing_outside_in.txt
  123. +164 −107 railties/doc/guides/{securing_rails_applications → source}/security.txt
  124. +358 −0 railties/doc/guides/source/stylesheets/base.css
  125. +35 −0 railties/doc/guides/source/stylesheets/forms.css
  126. +82 −0 railties/doc/guides/source/stylesheets/more.css
  127. +97 −0 railties/doc/guides/source/templates/guides.html.erb
  128. +165 −0 railties/doc/guides/source/templates/inline.css
  129. 0  railties/doc/guides/{testing_rails_applications → source}/testing_rails_applications.txt
  130. +13 −0 railties/lib/tasks/documentation.rake
View
3  .gitignore
@@ -5,7 +5,6 @@ activerecord/doc
actionpack/doc
actionmailer/doc
activesupport/doc
-railties/doc
activeresource/pkg
activerecord/pkg
actionpack/pkg
@@ -13,4 +12,6 @@ actionmailer/pkg
activesupport/pkg
railties/pkg
railties/test/500.html
+railties/doc/guides/html/images
+railties/doc/guides/html/stylesheets
*.rbc
View
12 actionpack/lib/action_view/helpers/date_helper.rb
@@ -406,15 +406,15 @@ def select_minute(datetime, options = {}, html_options = {})
# ==== Examples
# my_time = Time.now + 6.hours
#
- # # Generates a select field for minutes that defaults to the minutes for the time in my_time
- # select_minute(my_time)
+ # # Generates a select field for hours that defaults to the hour for the time in my_time
+ # select_hour(my_time)
#
- # # Generates a select field for minutes that defaults to the number given
- # select_minute(14)
+ # # Generates a select field for hours that defaults to the number given
+ # select_hour(13)
#
- # # Generates a select field for minutes that defaults to the minutes for the time in my_time
+ # # Generates a select field for hours that defaults to the minutes for the time in my_time
# # that is named 'stride' rather than 'second'
- # select_minute(my_time, :field_name => 'stride')
+ # select_hour(my_time, :field_name => 'stride')
#
def select_hour(datetime, options = {}, html_options = {})
DateTimeSelector.new(datetime, options, html_options).select_hour
View
3  activerecord/lib/active_record/associations.rb
@@ -624,7 +624,8 @@ module ClassMethods
# Adds one or more objects to the collection by setting their foreign keys to the collection's primary key.
# [collection.delete(object, ...)]
# Removes one or more objects from the collection by setting their foreign keys to +NULL+.
- # This will also destroy the objects if they're declared as +belongs_to+ and dependent on this model.
+ # Objects will be in addition destroyed if they're associated with <tt>:dependent => :destroy</tt>,
+ # and deleted if they're associated with <tt>:dependent => :delete_all</tt>.
# [collection=objects]
# Replaces the collections content by deleting and adding objects as appropriate.
# [collection_singular_ids]
View
8 activerecord/lib/active_record/associations/association_collection.rb
@@ -183,7 +183,13 @@ def count(*args)
end
- # Remove +records+ from this association. Does not destroy +records+.
+ # Removes +records+ from this association calling +before_remove+ and
+ # +after_remove+ callbacks.
+ #
+ # This method is abstract in the sense that +delete_records+ has to be
+ # provided by descendants. Note this method does not imply the records
+ # are actually removed from the database, that depends precisely on
+ # +delete_records+. They are in any case removed from the collection.
def delete(*records)
records = flatten_deeper(records)
records.each { |record| raise_on_type_mismatch(record) }
View
1  activerecord/lib/active_record/associations/has_many_association.rb
@@ -61,6 +61,7 @@ def insert_record(record)
record.save
end
+ # Deletes the records according to the <tt>:dependent</tt> option.
def delete_records(records)
case @reflection.options[:dependent]
when :destroy
View
4 activesupport/lib/active_support/multibyte/chars.rb
@@ -321,7 +321,7 @@ def reverse
# character.
#
# Example:
- # 'こにちわ'.mb_chars.slice(2..3).to_s #=> "ちわ"
+ # 'こんにちは'.mb_chars.slice(2..3).to_s #=> "にち"
def slice(*args)
if args.size > 2
raise ArgumentError, "wrong number of arguments (#{args.size} for 1)" # Do as if we were native
@@ -676,4 +676,4 @@ def chars(string) #:nodoc:
end
end
end
-end
+end
View
89 railties/Rakefile
@@ -272,57 +272,50 @@ Rake::RDocTask.new { |rdoc|
rdoc.rdoc_files.include('lib/commands/**/*.rb')
}
-# In this array, one defines the guides for which HTML output should be
-# generated. Specify the folder names of the guides. If the .txt filename
-# doesn't equal its folder name, then specify a hash: { 'folder_name' => 'basename' }
-guides = [
- 'getting_started_with_rails',
- # 'testing_rails_applications',
- 'creating_plugins',
- 'actioncontroller',
- 'migrations',
- { 'securing_rails_applications' => 'security' },
- { 'routing' => 'routing_outside_in' },
- { 'forms' =>'form_helpers' },
- { 'activerecord' => 'association_basics' },
- { 'activerecord' => 'finders' },
- { 'debugging' => 'debugging_rails_applications' },
- { 'caching' => 'caching_with_rails' },
- { 'benchmarking_and_profiling' => 'preamble' },
- { 'actionview' => 'layouts_and_rendering' }
-]
-
-guides_html_files = [] # autogenerated from the 'guides' variable.
-guides.each do |entry|
- if entry.is_a?(Hash)
- guide_folder = entry.keys.first
- guide_name = entry.values.first
- else
- guide_folder = entry
- guide_name = entry
- end
- input = "doc/guides/#{guide_folder}/#{guide_name}.txt"
- output = "doc/guides/#{guide_folder}/#{guide_name}.html"
- guides_html_files << output
- task output => Dir["doc/guides/#{guide_folder}/*.txt"] do
- ENV['MANUALSONRAILS_INDEX_URL'] = '../index.html'
- ENV.delete('MANUALSONRAILS_TOC')
- sh "mizuho", input, "--template", "manualsonrails", "--icons-dir", "../icons"
- end
-end
+desc "Generate guides for the framework"
+task :guides do
+ require 'mizuho/generator'
+
+ source = "doc/guides/source/"
+ html = "doc/guides/html/"
+ FileUtils.rm_r(html) if File.directory?(html)
+ FileUtils.mkdir(html)
+
+ template = File.expand_path("doc/guides/source/templates/guides.html.erb")
+ icons = File.expand_path("doc/guides/source/icons")
+
+ ignore = ['icons', 'images', 'templates', 'stylesheets']
+ ignore << 'active_record_basics.txt'
+
+ indexless = ['index.txt', 'authors.txt']
-['index', 'authors'].each do |guide|
- task "doc/guides/#{guide}.html" => "doc/guides/#{guide}.txt" do
- ENV.delete('MANUALSONRAILS_INDEX_URL')
- ENV['MANUALSONRAILS_TOC'] = 'no'
- sh "mizuho", "doc/guides/#{guide}.txt", "--template", "manualsonrails", "--icons-dir", "icons"
+ Dir.entries(source)[2..-1].each do |entry|
+ next if ignore.include?(entry)
+
+ if File.directory?(File.join(source, entry))
+ input = File.join(source, entry, 'index.txt')
+ output = File.join(html, entry)
+ else
+ input = File.join(source, entry)
+ output = File.join(html, entry).sub(/\.txt$/, '')
+ end
+
+ begin
+ puts "GENERATING => #{output}"
+ ENV['MANUALSONRAILS_TOC'] = 'no' if indexless.include?(entry)
+ Mizuho::Generator.new(input, output, template, false, icons).start
+ rescue Mizuho::GenerationError
+ STDERR.puts "*** ERROR"
+ exit 2
+ ensure
+ ENV.delete('MANUALSONRAILS_TOC')
+ end
end
-end
-desc "Generate HTML output for the guides"
-task :generate_guides => guides_html_files
-task :generate_guides => 'doc/guides/index.html'
-task :generate_guides => 'doc/guides/authors.html'
+ # Copy images and css files to html directory. These dirs are in .gitigore and shouldn't be source controlled.
+ FileUtils.cp_r File.join(source, 'images'), File.join(html, 'images')
+ FileUtils.cp_r File.join(source, 'stylesheets'), File.join(html, 'stylesheets')
+end
# Generate GEM ----------------------------------------------------------------------------
View
91 railties/doc/guides/actionview/helpers.markdown
@@ -1,91 +0,0 @@
-Helpers
-====================
-
-Helper Basics
-------------------------
-
-Helpers allow you to encapsulate rendering tasks as reusable functions. Helpers are modules, not classes, so their methods execute in the context in which they are called. They get included in a controller (typically the ApplicationController) using the helper function, like so
-
- Class ApplicationController < ActionController::Base
- …
- helper :menu
-
- def …
- end
- end
-
-In this way, methods in the menu helper are made available to any view or partial in your application. These methods can accept parameters, for example controller instance variables (eg; records or record collections gathered by you current controller), items from the view or partial’s locals[] hash or items from the params[] hash. You may wish to pass your controller instance variables and items from the params[] hash to the locals hash before rendering (See the section on partials). Helper methods can also accept an executable block of code.
-
-It is important to remember, though, that helpers are for rendering, and that they become available once a controller method has returned, while Rails is engaged in rendering the contents generated by a controller method. This means that helper methods are not available from within the methods of your controllers.
-
-Helpers can accomplish a variety of tasks, from formatting a complex tag for embedding content for a browser plugin (eg; Flash), to assembling a menu of options appropriate for the current context of your application, to generating sections of forms that get assembled on-the-fly.
-
-Helpers are organized around rendering tasks, so it is not necessary (nor necessarily desirable) to organize them around your application’s controllers or models. In fact, one of the benefits of helpers is that they are not connected via a rendering pipeline to specific controllers, like views and partials are. They can and should handle more generalized tasks.
-
-Here is a very simple, pseudo-example:
-
- module MenuHelper
- def menu(records, menu_options={})
- item_options = menu_options.merge({<some stuff>})
- items = records.collect |record| do
- menu_item(record, options)
- end
- content_tag(“ul”, items, options)
- end
-
- def menu_item(record, item_options={}))
- action = item_options[:action]
- action ||= “show”
- content_tag(“li”, link_to(record.title, :action => action, item_options)
- end
- end
-
-
-This helper will require that records passed into it have certain fields (notably :title). The helper could be written to use this as a default, allowing the field to be overwritten by an element of item_options.
-
-Look at the Rails API for examples of helpers included in Rails, eg; [`ActionView::Helpers::ActiveRecordHelper`](http://api.rubyonrails.org/classes/ActionView/Helpers/ActiveRecordHelper.html).
-
-Passing Blocks to Helper Methods
-------------------------
-
-We mentioned before that blocks can be passed to helper methods. This allows for an interesting wrinkle: a block passed to a helper method can cause it to render a partial, which can then be wrapped by the helper method’s output. This can make your helper method much more reusable. It doesn’t need to know anything about the internals about what it is rendering, it just contextualizes it for the page. You can also use the helper to modify the locals hash for the partial, based on some configuration information unique to the current controller. You could implement a flexible themes system in this way.
-
-
-Partials vs. Helpers?
-------------------------
-
-In general, the choice between using a partial vs. using a helper depends on the amount of flexibility you need. If the task is more about reacting to conditions than performing actual rendering, you may likely want a helper method. If you want to be able to call it from a variety of views, again, you may want to use a helper method. You can expect to extract helper methods out of code in views and partials during refactoring.
-
-
-Tutorial -- Calling a Helper [UNFINISHED]
-------------------------
-
-1. Create a Rails application using `rails helper_test`
-Notice the code:
-
- class ApplicationController < ActionController::Base
- helper :all # include all helpers, all the time
-For this tutorial, we'll keep this code, but you will likely want to exert more control over loading your helpers.
-
-2. Configure a database of your choice for the app.
-
-3. Inside of the `/app/helpers/` directory, create a new file called, `menu_helper.rb`. Write this in the file:
-
- module MenuHelpers
- def menu(records, item_proc=nil)
- items = records.collect{ |record|
- menu_item(record, item_proc)
- }
- content_tag("ul", items)
- end
-
- def menu_item(record, item_proc=nil)
- item_url = item_proc.call(record)
- item_url ||= { :action => :show }
- content_tag("li", link_to(record.name, item_url))
- end
- end
-
-4. Create a scaffold for some object in your app, using `./script/generate scaffold widgets`.
-5. Create a database table for your widgets, with at least the fields `name` and `id`. Create a few widgets.
-6. Call the menu command twice from `index.html.erb`, once using the default action, and once supplying a Proc to generate urls.
View
90 railties/doc/guides/actionview/partials.markdown
@@ -1,90 +0,0 @@
-A Guide to Using Partials
-===============================
-
-This guide elaborates on the use and function of partials in Ruby on Rails. As your Rails application grows, your view templates can start to contain a lot of duplicate view code. To manage and reduce this complexity, you can by abstract view template code into partials. Partials are reusable snippets of eRB template code stored in separate files with an underscore ('_') prefix.
-
-Partials can be located anywhere in the `app/views` directory. File extensions for partials work just like other template files, they bear an extension that denotes what kind of code they generate. For example, `_animal.html.erb` and `_animal.xml.erb` are valid filenames for partials.
-
-Partials can be inserted in eRB template code by calling the `render` method with the `:partial` option. For example:
-
- <%= render :partial => 'foo' %>
-
-This inserts the result of evaluating the template `_foo.html.erb` into the parent template file at this location. Note that `render` assumes that the partial will be in the same directory as the calling parent template and have the same file extension. Partials can be located anywhere within the `app/views` directory. To use a partial located in a different directory then it the parent, add a '/' before it:
-
- <%= render :partial => '/common/foo' %>
-
-Loads the partial file from the `app/views/common/_foo.html.erb` directory.
-
-Abstracting views into partials can be approached in a number of different ways, depending on the situation. Sometimes, the code that you are abstracting is a specialized view of an object or a collection of objects. Other times, you can look at partials as a reusable subroutine. We'll explore each of these approaches and when to use them as well as the syntax for calling them.
-
-Partials as a View Subroutine
------------------------------
-
-Using the `:locals` option, you can pass a hash of values which will be treated as local variables within the partial template.
-
- <%= render :partial => "person", :locals => { :name => "david" } %>
-
-The variable `name` contains the value `"david"` within the `_person.html.erb` template. Passing variables in this way allows you to create modular, reusable template files. Note that if you want to make local variables that are optional in some use cases, you will have to set them to a sentinel value such as `nil` when they have not been passed. So, in the example above, if the `name` variable is optional in some use cases, you must set:
-
- <% name ||= nil -%>
-
-So that you can later check:
-
- <% if name -%>
- <p>Hello, <%= name %>!</p>
- <% end -%>
-
-Otherwise, the if statement will throw an error at runtime.
-
-Another thing to be aware of is that instance variables that are visible to the parent view template are visible to the partial. So you might be tempted to do this:
-
- <%= render :partial => "person" %>
-
-And then within the partial:
-
- <% if @name -%>
- <p>Hello, <%= @name %>!</p>
- <% end -%>
-
-The potential snag here is that if multiple templates start to rely on this partial, you will need to maintain an instance variable with the same name across all of these templates and controllers. This approach can quickly become brittle if overused.
-
-Partials as a View of an Object
---------------------------------
-
-Another way to look at partials is to view them as mini-views of a particular object or instance variable. Use the `:object` option to pass an object assigns that object to an instance variable named after the partial itself. For example:
-
- # Renders the partial, making @new_person available through
- # the local variable 'person'
- render :partial => "person", :object => @new_person
-
-If the instance variable `name` in the parent template matches the name of the partial, you can use a shortcut:
-
- render :partial => "person"
-
-Now the value that was in `@person` in the parent template is accessible as `person` in the partial.
-
-Partials as a View of a Collection
------------------------------------
-
-Often it is the case that you need to display not just a single object, but a collection of objects. Rather than having to constantly nest the same partial within the same iterator code, Rails provides a syntactical shortcut using the `:collection` option:
-
- # Renders a collection of the same partial by making each element
- # of @winners available through the local variable "person" as it
- # builds the complete response.
- render :partial => "person", :collection => @winners
-
-This calls the `_person.html.erb` partial for each person in the `@winners` collection. This also creates a local variable within the partial called `partial_counter` which contains the index of the current value. So for example:
-
- <%= partial_counter %>) <%= person -%>
-
-Where `@winners` contains three people, produces the following output:
-
- 1) Bill
- 2) Jeff
- 3) Nick
-
-One last detail, you can place an arbitrary snippet of code in between the objects using the `:spacer_template` option.
-
- # Renders the same collection of partials, but also renders the
- # person_divider partial between each person partial.
- render :partial => "person", :collection => @winners, :spacer_template => "person_divider"
View
56 railties/doc/guides/activerecord/basics.markdown
@@ -1,56 +0,0 @@
-Active Record Basics
-====================
-
-
-
-The ActiveRecord Pattern
-------------------------
-
-Active Record (the library) conforms to the active record design pattern. The active record pattern is a design pattern often found in applications that use relational database. The name comes from by Martin Fowler's book *Patterns of Enterprise Application Architecture*, in which he describes an active record object as:
-
-> An object that wraps a row in a database table or view, encapsulates the database access, and adds domain logic on that data.
-
-So, an object that follows the active record pattern encapsulates both data and behavior; in other words, they are responsible for saving and loading to the database and also for any domain logic that acts on the data. The data structure of the Active Record should exactly match that of the database: one field in the class for each column in the table.
-
-The Active Record class typically has methods that do the following:
-
-* Construct an instances of an Active Record class from a SQL result
-* Construct a new class instance for insertion into the table
-* Get and set column values
-* Wrap business logic where appropriate
-* Update existing objects and update the related rows in the database
-
-Mapping Your Database
----------------------
-
-### Plural tables, singular classes ###
-
-### Schema lives in the database ###
-
-Creating Records
-----------------
-
-### Using save ###
-
-### Using create ###
-
-Retrieving Existing Rows
-------------------------
-
-### Using find ###
-
-### Using find_by_* ###
-
-Editing and Updating Rows
--------------------------
-
-### Editing an instance
-
-### Using update_all/update_attributes ###
-
-Deleting Data
--------------
-
-### Destroying a record ###
-
-### Deleting a record ###
View
55 railties/doc/guides/benchmarking_and_profiling/basics.txt
@@ -1,55 +0,0 @@
-== On The Road to Optimization ==
-=== Looking at the log file in regards to optimization ===
-
-You actually have been gathering data for benchmarking throughout your development cycle. Your log files are not just for error detection they also contain very useful information on how speedy your action is behaving.
-
-.Regular Log Output
-----------------------------------------------------------------------------
-
-Processing MediaController#index (for 127.0.0.1 at 2008-07-17 21:30:21) [GET]
-
- Session ID: BAh7BiIKZmxhc2hJQzonQWN0aW9uQ29udHJvbGxlcjo6Rmxhc2g6OkZsYXNo
-SGFzaHsABjoKQHVzZWR7AA==--cb57dad9c5e4704f0e1eddb3d498fef544faaf46
-
- Parameters: {"action"=>"index", "controller"=>"media"}
-
- Product Columns (0.003187) SHOW FIELDS FROM `products`
- Product Load (0.000597) SELECT * FROM `products` WHERE (`products`.`name` = 'Escape Plane') LIMIT 1
-
-Rendering template within layouts/standard
-
-Rendering media/index
- Track Load (0.001507) SELECT * FROM `tracks` WHERE (`tracks`.product_id = 1) 
- Track Columns (0.002280) SHOW FIELDS FROM `tracks`
-
-Rendered layouts/_header (0.00051)
-
-*Completed in 0.04310 (23 reqs/sec) | Rendering: 0.00819 (19%) | DB: 0.00757 (17%) | 200 OK [http://localhost/media]*
-----------------------------------------------------------------------------
-
-What concerns us here is the last line of the action.
-
-Completed in 0.04310 (23 reqs/sec) gives us the amount of requests this specific action can handle. 0.04310 is the total amount of time the process to complete and 23 reqs/sec is an estimation from this. As we will see this number is not strictly valid since is a single instance of the process. But it does give you a general feel as to how the action is performing.
-
-Rendering: 0.00819 (19%) is the amount in milliseconds and the percentage of total time needed to complete the action for rendering the view
-
-DB: 0.00757 (17%) is the amount in milliseconds and the percentage of total time needed to complete the action for querying the database
-
-Pretty easy right. But wait 17+19 equals 36. 36%! where is the rest of the time going? The rest of the time is being spent processing the controller. It is not shown but it is easy to calculate. Usually there is where most of your time ends on well functions actions.
-
-=== Why the Log File on it's Own is not Helpful ===
-
-So why can't we just use this to test our rails application. Technically that could work, but would be very stressful and slow. You don't have time to view your log after every request to see if your code is running quickly. Also a request that runs 100 reqs/sec might simply be an outlier and really usually runs at 20 reqs/sec. It's simply not enough information to do everything we need it to do but it's a start.
-
-But there is something else we must consider.
-
-=== A Simple Question, a Complicated Answer ===
-
-Is Completed in 0.04310 (23 reqs/sec) a good time. Seems like it doesn't it. 43 ms does not outrageous time for a dynamic page load. But is this a dynamic page load. Maybe it was all cached. In which case this is very slow. Or maybe I'm running on five year old equipment and this is actually blazing fast for my G3. The truth is that we can't answer the question given the data. This is part of benchmarking. We need a baseline. Through comparative analysis of all your pages in your app, and an simple dynamic page for a control we can determine how fast your pages are actually running and if any of them need to be optimized.
-
-And now for something completely different a short statistic lesson.
-
-
-
-
-
View
22 railties/doc/guides/benchmarking_and_profiling/definitions.txt
@@ -1,22 +0,0 @@
-== Terminology ==
-
-=== What We Mean by Benchmarking and Profiling ===
-
-Benchmarking: If you are new to programing you probably have heard the term mostly in comparative reviews of computer and graphic card specs. If you done a bit of coding you've probably seen in mostly in terms of comparing one language to another or iterations of the same language.
-
-Benchmarking in rails is more fine grained. It entails comparing and contrasting various parts and pages of an application against one another. Mostly one is looking for how long a page requires to render, but memory consumption is also an area of concern.
-
-While benchmarking two different sets of problems can emerge. Either you find that a few pages are performing worse then the rest of your app unexpectedly or that your whole entire application is slower then it reasonably should be. From there you start to profile to find the problem.
-
-Profiling: When a page or process is seen to be problematic due to speed or memory consumption we profile it. Meaning we measures the behavior as the page or process runs, particularly the frequency and duration of function calls. The goal of profiling is not to find bugs, but to eliminate bottlenecks and establish a baseline for future regression testing. It must be engaged in a carefully controlled process of measurement and analysis.
-
-==== What does that actually mean? ====
-
-You have to have a clear goal for when you benchmark and profile. It's very comparable to BDD where you are taking small steps towards a solution instead of trying to do it all in one large all encompassing step. A clearly defined set of expectations is essential for meaningful performance testing. We will talk more about this later.
-
-==== Where Does this Leave Us ====
-
-Numbers and data. You benchmark to compare, your profile to fix. It's all about gaining data to analyze and using that information to better your application. The most important thing you should take away at the moment that this must be done in a systematic way.
-
-So the next logical question is how do we get this data.
-
View
44 railties/doc/guides/benchmarking_and_profiling/preamble.txt
@@ -1,44 +0,0 @@
-Benchmarking and Profiling Rails
-================================
-Matthew Bergman <MzbPhoto@gmail.com>
-v0.6, September 2008
-
-Benchmarking and Profiling is an important part of the development process that is not nearly enough talked about for beginning developers. Its hard enough learning a language and successfully writing an application. But without a firm understanding optimization, production ready apps are a near impossibility. No matter how well you code, or how much you know about a language there is always something that will trip up your application.
-
-This article is my attempt to give the basic knowledge and methodology needed to optimize your application as painlessly as possible. We are are attempting this on two fronts. Both as a straight explanation and also through a real example of how benchmarking can speed up an application.
-
-The main things that are covered are
-
-* The basics of statistical analysis
-* Methodology behind benchmarking and profiling
-* Reading the log file for optimization
-* Performance Unit tests
-* Working with Ruby-Prof
-* HTTPREF #because you should know it
-* Overview of dedicated analysis options
-
-There are a lot of areas we need to cover so lets start.
-
-
-include::definitions.txt[]
-
-include::basics.txt[]
-
-include::statistics.txt[]
-
-include::edge_rails_features.txt[]
-
-include::rubyprof.txt[]
-
-include::digging_deeper.txt[]
-
-include::gameplan.txt[]
-
-include::appendix.txt[]
-
-
-
-
-
-
-
View
1,125 railties/doc/guides/html/actioncontroller_basics.html
@@ -0,0 +1,1125 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+ <title>Action Controller basics</title>
+ <!--[if lt IE 8]>
+ <script src="http://ie7-js.googlecode.com/svn/version/2.0(beta3)/IE8.js" type="text/javascript"></script>
+ <![endif]-->
+ <link href="stylesheets/base.css" media="screen" rel="Stylesheet" type="text/css" />
+ <link href="stylesheets/forms.css" media="screen" rel="Stylesheet" type="text/css" />
+ <link href="stylesheets/more.css" media="screen" rel="Stylesheet" type="text/css" />
+ <style type="text/css">
+ div#container {
+ max-width: 900px;
+ padding-bottom: 3em;
+}
+
+div#content {
+ margin-left: 200px;
+}
+
+div#container.notoc {
+ max-width: 600px;
+}
+
+.notoc div#content {
+ margin-left: 0;
+}
+
+pre {
+ line-height: 1.4em;
+}
+
+#content p tt {
+ background: #eeeeee;
+ border: solid 1px #cccccc;
+ padding: 3px;
+}
+
+dt {
+ font-weight: bold;
+}
+
+#content dt tt {
+ font-size: 10pt;
+}
+
+dd {
+ margin-left: 3em;
+}
+
+#content dt tt, #content pre tt {
+ background: none;
+ padding: 0;
+ border: 0;
+}
+
+#content .olist ol {
+ margin-left: 2em;
+}
+
+#header {
+ position: relative;
+ max-width: 840px;
+ margin-left: auto;
+ margin-right: auto;
+}
+
+#header.notoc {
+ max-width: 580px;
+}
+
+#logo {
+ position: absolute;
+ left: 10px;
+ top: 10px;
+ width: 110px;
+ height: 140px;
+}
+
+div#header h1#site_title {
+ background: url('images/ruby_on_rails_by_mike_rundle2.gif') top left no-repeat;
+ position: absolute;
+ width: 392px;
+ height: 55px;
+ left: 145px;
+ top: 20px;
+ margin: 0;
+ padding: 0;
+}
+
+#site_title span {
+ display: none;
+}
+
+#site_title_tagline {
+ display: none;
+}
+
+ul#navMain {
+ position: absolute;
+ margin: 0;
+ padding: 0;
+ top: 97px;
+ left: 145px;
+}
+
+.left-floaty, .right-floaty {
+ padding: 15px;
+}
+
+.admonitionblock,
+.tableblock {
+ margin-left: 1em;
+ margin-right: 1em;
+ margin-top: 0.25em;
+ margin-bottom: 1em;
+}
+
+.admonitionblock .icon {
+ padding-right: 8px;
+}
+
+.admonitionblock .content {
+ border: solid 1px #ffda78;
+ background: #fffebd;
+ padding: 10px;
+ padding-top: 8px;
+ padding-bottom: 8px;
+}
+
+.admonitionblock .title {
+ font-size: 140%;
+ margin-bottom: 0.5em;
+}
+
+.tableblock table {
+ border: solid 1px #aaaaff;
+ background: #f0f0ff;
+}
+
+.tableblock th {
+ background: #e0e0e0;
+}
+
+.tableblock th,
+.tableblock td {
+ padding: 3px;
+ padding-left: 5px;
+ padding-right: 5px;
+}
+
+.sidebarblock {
+ margin-top: 0.25em;
+ margin: 1em;
+ border: solid 1px #ccccbb;
+ padding: 8px;
+ background: #ffffe0;
+}
+
+.sidebarblock .sidebar-title {
+ font-size: 140%;
+ font-weight: 600;
+ margin-bottom: 0.3em;
+}
+
+.sidebarblock .sidebar-content > .para:last-child > p {
+ margin-bottom: 0;
+}
+
+.sidebarblock .sidebar-title a {
+ text-decoration: none;
+}
+
+.sidebarblock .sidebar-title a:hover {
+ text-decoration: underline;
+}
+
+ </style>
+</head>
+<body>
+ <div id="header" >
+ <div id="logo">
+ <a href="index.html" title="Ruby on Rails"><img src="images/rails_logo_remix.gif" alt="Rails" height="140" width="110" /></a>
+ </div>
+
+ <h1 id="site_title"><span>Ruby on Rails</span></h1>
+ <h2 id="site_title_tagline">Sustainable productivity for web-application development</h2>
+
+ <ul id="navMain">
+ <li class="first-child"><a href="http://www.rubyonrails.org/" title="Ruby on Rails" class="ruby_on_rails">Ruby on Rails</a></li>
+ <li><a class="manuals" href="index.html" title="Manuals Index">Guides Index</a></li>
+ </ul>
+ </div>
+
+ <div id="container">
+
+ <div id="sidebar">
+ <h2>Chapters</h2>
+ <ol>
+ <li>
+ <a href="#_what_does_a_controller_do">What does a controller do?</a>
+ </li>
+ <li>
+ <a href="#_methods_and_actions">Methods and actions</a>
+ </li>
+ <li>
+ <a href="#_parameters">Parameters</a>
+ <ul>
+
+ <li><a href="#_hash_and_array_parameters">Hash and array parameters</a></li>
+
+ <li><a href="#_routing_parameters">Routing parameters</a></li>
+
+ </ul>
+ </li>
+ <li>
+ <a href="#_session">Session</a>
+ <ul>
+
+ <li><a href="#_disabling_the_session">Disabling the session</a></li>
+
+ <li><a href="#_accessing_the_session">Accessing the session</a></li>
+
+ <li><a href="#_the_flash">The flash</a></li>
+
+ </ul>
+ </li>
+ <li>
+ <a href="#_cookies">Cookies</a>
+ </li>
+ <li>
+ <a href="#_filters">Filters</a>
+ <ul>
+
+ <li><a href="#_after_filters_and_around_filters">After filters and around filters</a></li>
+
+ <li><a href="#_other_ways_to_use_filters">Other ways to use filters</a></li>
+
+ </ul>
+ </li>
+ <li>
+ <a href="#_verification">Verification</a>
+ </li>
+ <li>
+ <a href="#_the_request_and_response_objects">The request and response objects</a>
+ <ul>
+
+ <li><a href="#_the_request">The request</a></li>
+
+ <li><a href="#_the_response">The response</a></li>
+
+ </ul>
+ </li>
+ <li>
+ <a href="#_http_basic_authentication">HTTP Basic Authentication</a>
+ </li>
+ <li>
+ <a href="#_streaming_and_file_downloads">Streaming and file downloads</a>
+ <ul>
+
+ <li><a href="#_sending_files">Sending files</a></li>
+
+ <li><a href="#_restful_downloads">RESTful downloads</a></li>
+
+ </ul>
+ </li>
+ <li>
+ <a href="#_parameter_filtering">Parameter filtering</a>
+ </li>
+ <li>
+ <a href="#_rescue">Rescue</a>
+ <ul>
+
+ <li><a href="#_the_default_500_and_404_templates">The default 500 and 404 templates</a></li>
+
+ <li><a href="#_tt_rescue_from_tt"><tt>rescue_from</tt></a></li>
+
+ </ul>
+ </li>
+ </ol>
+ </div>
+
+ <div id="content">
+ <h1>Action Controller basics</h1>
+ <div id="preamble">
+<div class="sectionbody">
+<div class="para"><p>In this guide you will learn how controllers work and how they fit into the request cycle in your application. You will learn how to make use of the many tools provided by Action Controller to work with the session, cookies and filters and how to use the built-in HTTP authentication and data streaming facilities. In the end, we will take a look at some tools that will be useful once your controllers are ready and working, like how to filter sensitive parameters from the log and how to rescue and deal with exceptions that may be raised during the request.</p></div>
+</div>
+</div>
+<h2 id="_what_does_a_controller_do">1. What does a controller do?</h2>
+<div class="sectionbody">
+<div class="para"><p>Action Controller is the C in MVC. After routing has determined which controller to use for a request, your controller is responsible for making sense of the request and producing the appropriate output. Luckily, Action Controller does most of the groundwork for you and uses smart conventions to make this as straight-forward as possible.</p></div>
+<div class="para"><p>For most conventional RESTful applications, the controller will receive the request (this is invisible to you as the developer), fetch or save data from a model and use a view to create HTML output. If your controller needs to do things a little differently, that's not a problem, this is just the most common way for a controller to work.</p></div>
+<div class="para"><p>A controller can thus be thought of as a middle man between models and views. It makes the model data available to the view so it can display it to the user, and it saves or updates data from the user to the model.</p></div>
+</div>
+<h2 id="_methods_and_actions">2. Methods and actions</h2>
+<div class="sectionbody">
+<div class="para"><p>A controller is a Ruby class which inherits from ActionController::Base and has methods just like any other class. Usually these methods correspond to actions in MVC, but they can just as well be helpful methods which can be called by actions. When your application receives a request, the routing will determine which controller and action to run. Then an instance of that controller will be created and the method corresponding to the action (the method with the same name as the action) gets run.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ClientsController <span style="color: #990000">&lt;</span> ActionController<span style="color: #990000">::</span>Base
+
+ <span style="font-style: italic"><span style="color: #9A1900"># Actions are public methods</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> new
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+ <span style="font-style: italic"><span style="color: #9A1900"># These methods are responsible for producing output</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> edit
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+<span style="font-style: italic"><span style="color: #9A1900"># Helper methods are private and can not be used as actions</span></span>
+private
+
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> foo
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<div class="para"><p>Private methods in a controller are also used as filters, which will be covered later in this guide.</p></div>
+<div class="para"><p>As an example, if the user goes to <tt>/clients/new</tt> in your application to add a new client, a ClientsController instance will be created and the <tt>new</tt> method will be run. Note that the empty method from the example above could work just fine because Rails will by default render the <tt>new.html.erb</tt> view unless the action says otherwise. The <tt>new</tt> method could make available to the view a <tt>@client</tt> instance variable by creating a new Client:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">def</span></span> new
+ <span style="color: #009900">@client</span> <span style="color: #990000">=</span> Client<span style="color: #990000">.</span>new
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<div class="para"><p>The Layouts &amp; rendering guide explains this in more detail.</p></div>
+</div>
+<h2 id="_parameters">3. Parameters</h2>
+<div class="sectionbody">
+<div class="para"><p>You will probably want to access data sent in by the user or other parameters in your controller actions. There are two kinds of parameters possible in a web application. The first are parameters that are sent as part of the URL, query string parameters. The query string is everything after "?" in the URL. The second type of parameter is usually referred to as POST data. This information usually comes from a HTML form which has been filled in by the user. It's called POST data because it can only be sent as part of an HTTP POST request. Rails does not make any distinction between query string parameters and POST parameters, and both are available in the <tt>params</tt> hash in your controller:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ClientsController <span style="color: #990000">&lt;</span> ActionController<span style="color: #990000">::</span>Base
+
+ <span style="font-style: italic"><span style="color: #9A1900"># This action uses query string parameters because it gets run by a HTTP GET request,</span></span>
+ <span style="font-style: italic"><span style="color: #9A1900"># but this does not make any difference to the way in which the parameters are accessed.</span></span>
+ <span style="font-style: italic"><span style="color: #9A1900"># The URL for this action would look like this in order to list activated clients: /clients?status=activated</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> index
+ <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> params<span style="color: #990000">[:</span>status<span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"activated"</span>
+ <span style="color: #009900">@clients</span> <span style="color: #990000">=</span> Client<span style="color: #990000">.</span>activated
+ <span style="font-weight: bold"><span style="color: #0000FF">else</span></span>
+ <span style="color: #009900">@clients</span> <span style="color: #990000">=</span> Client<span style="color: #990000">.</span>unativated
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+ <span style="font-style: italic"><span style="color: #9A1900"># This action uses POST parameters. They are most likely coming from an HTML</span></span>
+ <span style="font-style: italic"><span style="color: #9A1900"># form which the user has submitted. The URL for this RESTful request will</span></span>
+ <span style="font-style: italic"><span style="color: #9A1900"># be "/clients", and the data will be sent as part of the request body.</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> create
+ <span style="color: #009900">@client</span> <span style="color: #990000">=</span> Client<span style="color: #990000">.</span>new<span style="color: #990000">(</span>params<span style="color: #990000">[:</span>client<span style="color: #990000">])</span>
+ <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #009900">@client</span><span style="color: #990000">.</span>save
+ redirect_to <span style="color: #009900">@client</span>
+ <span style="font-weight: bold"><span style="color: #0000FF">else</span></span>
+ <span style="font-style: italic"><span style="color: #9A1900"># This line overrides the default rendering behavior, which would have been</span></span>
+ <span style="font-style: italic"><span style="color: #9A1900"># to render the "create" view.</span></span>
+ render <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"new"</span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<h3 id="_hash_and_array_parameters">3.1. Hash and array parameters</h3>
+<div class="para"><p>The params hash is not limited to one-dimensional keys and values. It can contain arrays and (nested) hashes. To send an array of values, append "[]" to the key name:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>GET /clients?ids[]=1&amp;ids[2]&amp;ids[]=3</tt></pre>
+</div></div>
+<div class="para"><p>The value of <tt>params[:ids]</tt> will now be <tt>["1", "2", "3"]</tt>. Note that parameter values are always strings; Rails makes no attempt to guess or cast the type.</p></div>
+<div class="para"><p>To send a hash you include the key name inside the brackets:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>&lt;form action="/clients" method="post"&gt;
+ &lt;input type="text" name="client[name]" value="Acme" /&gt;
+ &lt;input type="text" name="client[phone]" value="12345" /&gt;
+ &lt;input type="text" name="client[address][postcode]" value="12345" /&gt;
+ &lt;input type="text" name="client[address][city]" value="Carrot City" /&gt;
+&lt;/form&gt;</tt></pre>
+</div></div>
+<div class="para"><p>The value of <tt>params[:client]</tt> when this form is submitted will be <tt>{:name &#8658; "Acme", :phone &#8658; "12345", :address &#8658; {:postcode &#8658; "12345", :city &#8658; "Carrot City"}}</tt>. Note the nested hash in <tt>params[:client][:address]</tt>.</p></div>
+<h3 id="_routing_parameters">3.2. Routing parameters</h3>
+<div class="para"><p>The <tt>params</tt> hash will always contain the <tt>:controller</tt> and <tt>:action</tt> keys, but you should use the methods <tt>controller_name</tt> and <tt>action_name</tt> instead to access these values. Any other parameters defined by the routing, such as <tt>:id</tt> will also be available.</p></div>
+</div>
+<h2 id="_session">4. Session</h2>
+<div class="sectionbody">
+<div class="para"><p>Your application has a session for each user in which you can store small amounts of data that will be persisted between requests. The session is only available in the controller and can use one of a number of different storage mechanisms:</p></div>
+<div class="ilist"><ul>
+<li>
+<p>
+CookieStore - Stores everything on the client.
+</p>
+</li>
+<li>
+<p>
+DRBStore - Stores the data on a DRb client.
+</p>
+</li>
+<li>
+<p>
+MemCacheStore - Stores the data in MemCache.
+</p>
+</li>
+<li>
+<p>
+ActiveRecordStore - Stores the data in a database using Active Record.
+</p>
+</li>
+</ul></div>
+<div class="para"><p>All session stores store the session id in a cookie - there is no other way of passing it to the server. Most stores also use this key to locate the session data on the server.</p></div>
+<div class="para"><p>The default and recommended store, the Cookie Store, does not store session data on the server, but in the cookie itself. The data is cryptographically signed to make it tamper-proof, but it is not encrypted, so anyone with access to it can read its contents. It can only store about 4kB of data - much less than the others - but this is usually enough. Storing large amounts of data is discouraged no matter which session store your application uses. Expecially discouraged is storing complex objects (anything other than basic Ruby objects, the primary example being model instances) in the session, as the server might not be able to reassemble them between requests, which will result in an error. The Cookie Store has the added advantage that it does not require any setting up beforehand - Rails will generate a "secret key" which will be used to sign the cookie when you create the application.</p></div>
+<div class="para"><p>If you need a different session storage mechanism, you can change it in the <tt>config/environment.rb</tt> file:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-style: italic"><span style="color: #9A1900"># Set to one of [:active_record_store, :drb_store, :mem_cache_store, :cookie_store]</span></span>
+config<span style="color: #990000">.</span>action_controller<span style="color: #990000">.</span>session_store <span style="color: #990000">=</span> <span style="color: #990000">:</span>active_record_store
+</tt></pre></div></div>
+<h3 id="_disabling_the_session">4.1. Disabling the session</h3>
+<div class="para"><p>Sometimes you don't need a session, and you can turn it off to avoid the unnecessary overhead. To do this, use the <a href="http://api.rubyonrails.org/classes/ActionController/SessionManagement/ClassMethods.html#M000649">session</a> class method in your controller:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ApplicationController <span style="color: #990000">&lt;</span> ActionController<span style="color: #990000">::</span>Base
+ session <span style="color: #990000">:</span>off
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<div class="para"><p>You can also turn the session on or off for a single controller:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-style: italic"><span style="color: #9A1900"># The session is turned off by default in ApplicationController, but we</span></span>
+<span style="font-style: italic"><span style="color: #9A1900"># want to turn it on for log in/out.</span></span>
+<span style="font-weight: bold"><span style="color: #0000FF">class</span></span> LoginsController <span style="color: #990000">&lt;</span> ActionController<span style="color: #990000">::</span>Base
+ session <span style="color: #990000">:</span>on
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<div class="para"><p>Or even a single action:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ProductsController <span style="color: #990000">&lt;</span> ActionController<span style="color: #990000">::</span>Base
+ session <span style="color: #990000">:</span>on<span style="color: #990000">,</span> <span style="color: #990000">:</span>only <span style="color: #990000">=&gt;</span> <span style="color: #990000">[:</span>create<span style="color: #990000">,</span> <span style="color: #990000">:</span>update<span style="color: #990000">]</span>
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<h3 id="_accessing_the_session">4.2. Accessing the session</h3>
+<div class="para"><p>In your controller you can access the session through the <tt>session</tt> instance method.</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/note.png" alt="Note" />
+</td>
+<td class="content">There are two <tt>session</tt> methods, the class and the instance method. The class method which is described above is used to turn the session on and off while the instance method described below is used to access session values. The class method is used outside of method definitions while the instance methods is used inside methods, in actions or filters.</td>
+</tr></table>
+</div>
+<div class="para"><p>Session values are stored using key/value pairs like a hash:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ApplicationController <span style="color: #990000">&lt;</span> ActionController<span style="color: #990000">::</span>Base
+
+private
+
+ <span style="font-style: italic"><span style="color: #9A1900"># Finds the User with the ID stored in the session with the key :current_user_id</span></span>
+ <span style="font-style: italic"><span style="color: #9A1900"># This is a common way to do user login in a Rails application; logging in sets the</span></span>
+ <span style="font-style: italic"><span style="color: #9A1900"># session value and logging out removes it.</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> current_user
+ <span style="color: #009900">@_current_user</span> <span style="color: #990000">||=</span> session<span style="color: #990000">[:</span>current_user_id<span style="color: #990000">]</span> <span style="color: #990000">&amp;&amp;</span> User<span style="color: #990000">.</span>find<span style="color: #990000">(</span>session<span style="color: #990000">[:</span>current_user_id<span style="color: #990000">])</span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<div class="para"><p>To store something in the session, just assign it to the key like a hash:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> LoginsController <span style="color: #990000">&lt;</span> ApplicationController
+
+ <span style="font-style: italic"><span style="color: #9A1900"># "Create" a login, aka "log the user in"</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> create
+ <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> user <span style="color: #990000">=</span> User<span style="color: #990000">.</span>authenticate<span style="color: #990000">(</span>params<span style="color: #990000">[:</span>username<span style="color: #990000">,</span> params<span style="color: #990000">[:</span>password<span style="color: #990000">])</span>
+ <span style="font-style: italic"><span style="color: #9A1900"># Save the user ID in the session so it can be used in subsequent requests</span></span>
+ session<span style="color: #990000">[:</span>current_user_id<span style="color: #990000">]</span> <span style="color: #990000">=</span> user<span style="color: #990000">.</span>id
+ redirect_to root_url
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<div class="para"><p>To remove something from the session, assign that key to be <tt>nil</tt>:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> LoginsController <span style="color: #990000">&lt;</span> ApplicationController
+
+ <span style="font-style: italic"><span style="color: #9A1900"># "Delete" a login, aka "log the user out"</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> destroy
+ <span style="font-style: italic"><span style="color: #9A1900"># Remove the user id from the session</span></span>
+ session<span style="color: #990000">[:</span>current_user_id<span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">nil</span></span>
+ redirect_to root_url
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<div class="para"><p>To reset the entire session, use <a href="http://api.rubyonrails.org/classes/ActionController/Base.html#M000855">reset_session</a>.</p></div>
+<h3 id="_the_flash">4.3. The flash</h3>
+<div class="para"><p>The flash is a special part of the session which is cleared with each request. This means that values stored there will only be available in the next request, which is useful for storing error messages etc. It is accessed in much the same way as the session, like a hash. Let's use the act of logging out as an example. The controller can set a message which will be displayed to the user on the next request:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> LoginsController <span style="color: #990000">&lt;</span> ApplicationController
+
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> destroy
+ session<span style="color: #990000">[:</span>current_user_id<span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">nil</span></span>
+ flash<span style="color: #990000">[:</span>notice<span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"You have successfully logged out"</span>
+ redirect_to root_url
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<div class="para"><p>The <tt>destroy</tt> action redirects to the application's <tt>root_url</tt>, where the message will be displayed. Note that it's entirely up to the next action to decide what, if anything, it will do with what the previous action put in the flash. It's conventional to a display eventual errors or notices from the flash in the application's layout:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>&lt;html&gt;
+ &lt;!-- &lt;head/&gt; --&gt;
+ &lt;body&gt;
+ &lt;% if flash[:notice] -%&gt;
+ &lt;p class="notice"&gt;&lt;%= flash[:notice] %&gt;&lt;/p&gt;
+ &lt;% end -%&gt;
+ &lt;% if flash[:error] -%&gt;
+ &lt;p class="error"&gt;&lt;%= flash[:error] %&gt;&lt;/p&gt;
+ &lt;% end -%&gt;
+ &lt;!-- more content --&gt;
+ &lt;/body&gt;
+&lt;/html&gt;</tt></pre>
+</div></div>
+<div class="para"><p>This way, if an action sets an error or a notice message, the layout will display it automatically.</p></div>
+<div class="para"><p>If you want a flash value to be carried over to another request, use the <tt>keep</tt> method:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> MainController <span style="color: #990000">&lt;</span> ApplicationController
+
+ <span style="font-style: italic"><span style="color: #9A1900"># Let's say this action corresponds to root_url, but you want all requests here to be redirected to</span></span>
+ <span style="font-style: italic"><span style="color: #9A1900"># UsersController#index. If an action sets the flash and redirects here, the values would normally be</span></span>
+ <span style="font-style: italic"><span style="color: #9A1900"># lost when another redirect happens, but you can use keep to make it persist for another request.</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> index
+ flash<span style="color: #990000">.</span>keep <span style="font-style: italic"><span style="color: #9A1900"># Will persist all flash values. You can also use a key to keep only that value: flash.keep(:notice)</span></span>
+ redirect_to users_url
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<h4 id="_flash_now">4.3.1. flash.now</h4>
+<div class="para"><p>By default, adding values to the flash will make them available to the next request, but sometimes you may want to access those values in the same request. For example, if the <tt>create</tt> action fails to save a resource and you render the <tt>new</tt> template directly, that's not going to result in a new request, but you may still want to display a message using the flash. To do this, you can use <tt>flash.now</tt> in the same way you use the normal <tt>flash</tt>:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ClientsController <span style="color: #990000">&lt;</span> ApplicationController
+
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> create
+ <span style="color: #009900">@client</span> <span style="color: #990000">=</span> Client<span style="color: #990000">.</span>new<span style="color: #990000">(</span>params<span style="color: #990000">[:</span>client<span style="color: #990000">])</span>
+ <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #009900">@client</span><span style="color: #990000">.</span>save
+ <span style="font-style: italic"><span style="color: #9A1900"># ...</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">else</span></span>
+ flash<span style="color: #990000">.</span>now<span style="color: #990000">[:</span>error<span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"Could not save client"</span>
+ render <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"new"</span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+</div>
+<h2 id="_cookies">5. Cookies</h2>
+<div class="sectionbody">
+<div class="para"><p>Your application can store small amounts of data on the client - called cookies - that will be persisted across requests and even sessions. Rails provides easy access to cookies via the <tt>cookies</tt> method, which - much like the <tt>session</tt> - works like a hash:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> CommentsController <span style="color: #990000">&lt;</span> ApplicationController
+
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> new
+ <span style="font-style: italic"><span style="color: #9A1900">#Auto-fill the commenter's name if it has been stored in a cookie</span></span>
+ <span style="color: #009900">@comment</span> <span style="color: #990000">=</span> Comment<span style="color: #990000">.</span>new<span style="color: #990000">(:</span>name <span style="color: #990000">=&gt;</span> cookies<span style="color: #990000">[:</span>commenter_name<span style="color: #990000">])</span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> create
+ <span style="color: #009900">@comment</span> <span style="color: #990000">=</span> Comment<span style="color: #990000">.</span>new<span style="color: #990000">(</span>params<span style="color: #990000">[:</span>comment<span style="color: #990000">])</span>
+ <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #009900">@comment</span><span style="color: #990000">.</span>save
+ flash<span style="color: #990000">[:</span>notice<span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"Thanks for your comment!"</span>
+ <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> params<span style="color: #990000">[:</span>remember_name<span style="color: #990000">]</span>
+ <span style="font-style: italic"><span style="color: #9A1900"># Remember the commenter's name</span></span>
+ cookies<span style="color: #990000">[:</span>commenter_name<span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="color: #009900">@comment</span><span style="color: #990000">.</span>name
+ <span style="font-weight: bold"><span style="color: #0000FF">else</span></span>
+ <span style="font-style: italic"><span style="color: #9A1900"># Don't remember, and delete the name if it has been remembered before</span></span>
+ cookies<span style="color: #990000">.</span>delete<span style="color: #990000">(:</span>commenter_name<span style="color: #990000">)</span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+ redirect_to <span style="color: #009900">@comment</span><span style="color: #990000">.</span>article
+ <span style="font-weight: bold"><span style="color: #0000FF">else</span></span>
+ render <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"new"</span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<div class="para"><p>Note that while for session values, you set the key to <tt>nil</tt>, to delete a cookie value, you use <tt>cookies.delete(:key)</tt>.</p></div>
+</div>
+<h2 id="_filters">6. Filters</h2>
+<div class="sectionbody">
+<div class="para"><p>Filters are methods that are run before, after or "around" a controller action. For example, one filter might check to see if the logged in user has the right credentials to access that particular controller or action. Filters are inherited, so if you set a filter on ApplicationController, it will be run on every controller in your application. A common, simple filter is one which requires that a user is logged in for an action to be run. Let's define the filter method first:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ApplicationController <span style="color: #990000">&lt;</span> ActionController<span style="color: #990000">::</span>Base
+
+private
+
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> require_login
+ <span style="font-weight: bold"><span style="color: #0000FF">unless</span></span> logged_in?
+ flash<span style="color: #990000">[:</span>error<span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"You must be logged in to access this section"</span>
+ redirect_to new_login_url <span style="font-style: italic"><span style="color: #9A1900"># Prevents the current action from running</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+ <span style="font-style: italic"><span style="color: #9A1900"># The logged_in? method simply returns true if the user is logged in and</span></span>
+ <span style="font-style: italic"><span style="color: #9A1900"># false otherwise. It does this by "booleanizing" the current_user method</span></span>
+ <span style="font-style: italic"><span style="color: #9A1900"># we created previously using a double ! operator. Note that this is not</span></span>
+ <span style="font-style: italic"><span style="color: #9A1900"># common in Ruby and is discouraged unless you really mean to convert something</span></span>
+ <span style="font-style: italic"><span style="color: #9A1900"># into true or false.</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> logged_in?
+ <span style="color: #990000">!!</span>current_user
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<div class="para"><p>The method simply stores an error message in the flash and redirects to the login form if the user is not logged in. If a before filter (a filter which is run before the action) renders or redirects, the action will not run. If there are additional filters scheduled to run after the rendering/redirecting filter, they are also cancelled. To use this filter in a controller, use the <a href="http://api.rubyonrails.org/classes/ActionController/Filters/ClassMethods.html#M000704">before_filter</a> method:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ApplicationController <span style="color: #990000">&lt;</span> ActionController<span style="color: #990000">::</span>Base
+
+ before_filter <span style="color: #990000">:</span>require_login
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<div class="para"><p>In this example, the filter is added to ApplicationController and thus all controllers in the application. This will make everything in the application require the user to be logged in in order to use it. For obvious reasons (the user wouldn't be able to log in in the first place!), not all controllers or actions should require this, so to prevent this filter from running you can use <a href="http://api.rubyonrails.org/classes/ActionController/Filters/ClassMethods.html#M000711">skip_before_filter</a> :</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> LoginsController <span style="color: #990000">&lt;</span> Application
+
+ skip_before_filter <span style="color: #990000">:</span>require_login<span style="color: #990000">,</span> <span style="color: #990000">:</span>only <span style="color: #990000">=&gt;</span> <span style="color: #990000">[:</span>new<span style="color: #990000">,</span> <span style="color: #990000">:</span>create<span style="color: #990000">]</span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<div class="para"><p>Now, the LoginsController's "new" and "create" actions will work as before without requiring the user to be logged in. The <tt>:only</tt> option is used to only skip this filter for these actions, and there is also an <tt>:except</tt> option which works the other way. These options can be used when adding filters too, so you can add a filter which only runs for selected actions in the first place.</p></div>
+<h3 id="_after_filters_and_around_filters">6.1. After filters and around filters</h3>
+<div class="para"><p>In addition to the before filters, you can run filters after an action has run or both before and after. The after filter is similar to the before filter, but because the action has already been run it has access to the response data that's about to be sent to the client. Obviously, after filters can not stop the action from running. Around filters are responsible for running the action, but they can choose not to, which is the around filter's way of stopping it.</p></div>
+<div class="para"><p>TODO: Find a real example for an around filter</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-style: italic"><span style="color: #9A1900"># Example taken from the Rails API filter documentation:</span></span>
+<span style="font-style: italic"><span style="color: #9A1900"># http://api.rubyonrails.org/classes/ActionController/Filters/ClassMethods.html</span></span>
+<span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ApplicationController <span style="color: #990000">&lt;</span> Application
+
+ around_filter <span style="color: #990000">:</span>catch_exceptions
+
+private
+
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> catch_exceptions
+ <span style="font-weight: bold"><span style="color: #0000FF">yield</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">rescue</span></span> <span style="color: #990000">=&gt;</span> exception
+ logger<span style="color: #990000">.</span>debug <span style="color: #FF0000">"Caught exception! #{exception}"</span>
+ <span style="font-weight: bold"><span style="color: #0000FF">raise</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<h3 id="_other_ways_to_use_filters">6.2. Other ways to use filters</h3>
+<div class="para"><p>While the most common way to use filters is by creating private methods and using *_filter to add them, there are two other ways to do the same thing.</p></div>
+<div class="para"><p>The first is to use a block directly with the *_filter methods. The block receives the controller as an argument, and the <tt>require_login</tt> filter from above could be rewritte to use a block:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ApplicationController <span style="color: #990000">&lt;</span> ActionController<span style="color: #990000">::</span>Base
+
+ before_filter <span style="color: #FF0000">{</span> <span style="color: #990000">|</span>controller<span style="color: #990000">|</span> redirect_to new_login_url <span style="font-weight: bold"><span style="color: #0000FF">unless</span></span> controller<span style="color: #990000">.</span>send<span style="color: #990000">(:</span>logged_in?<span style="color: #990000">)</span> <span style="color: #FF0000">}</span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<div class="para"><p>Note that the filter in this case uses <tt>send</tt> because the <tt>logged_in?</tt> method is private and the filter is not run in the scope of the controller. This is not the recommended way to implement this particular filter, but in more simple cases it might be useful.</p></div>
+<div class="para"><p>The second way is to use a class (actually, any object that responds to the right methods will do) to handle the filtering. This is useful in cases that are more complex than can not be implemented in a readable and reusable way using the two other methods. As an example, we will rewrite the login filter again to use a class:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ApplicationController <span style="color: #990000">&lt;</span> ActionController<span style="color: #990000">::</span>Base
+
+ before_filter LoginFilter
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">class</span></span> LoginFilter
+
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>filter<span style="color: #990000">(</span>controller<span style="color: #990000">)</span>
+ <span style="font-weight: bold"><span style="color: #0000FF">unless</span></span> logged_in?
+ controller<span style="color: #990000">.</span>flash<span style="color: #990000">[:</span>error<span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"You must be logged in to access this section"</span>
+ controller<span style="color: #990000">.</span>redirect_to controller<span style="color: #990000">.</span>new_login_url
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<div class="para"><p>Again, this is not an ideal example for this filter, because it's not run in the scope of the controller but gets it passed as an argument. The filter class has a class method <tt>filter</tt> which gets run before or after the action, depending on if it's a before or after filter. Classes used as around filters can also use the same <tt>filter</tt> method, which will get run in the same way. The method must <tt>yield</tt> to execute the action. Alternatively, it can have both a <tt>before</tt> and an <tt>after</tt> method that are run before and after the action.</p></div>
+<div class="para"><p>The Rails API documentation has <a href="http://api.rubyonrails.org/classes/ActionController/Filters/ClassMethods.html">more information on using filters</a>.</p></div>
+</div>
+<h2 id="_verification">7. Verification</h2>
+<div class="sectionbody">
+<div class="para"><p>Verifications make sure certain criterias are met in order for a controller or action to run. They can specify that a certain key (or several keys in the form of an array) is present in the <tt>params</tt>, <tt>session</tt> or <tt>flash</tt> hashes or that a certain HTTP method was used or that the request was made using XMLHTTPRequest (Ajax). The default action taken when these criterias are not met is to render a 400 Bad Request response, but you can customize this by specifying a redirect URL or rendering something else and you can also add flash messages and HTTP headers to the response. It is described in the <a href="http://api.rubyonrails.org/classes/ActionController/Verification/ClassMethods.html">API codumentation</a> as "essentially a special kind of before_filter".</p></div>
+<div class="para"><p>Let's see how we can use verification to make sure the user supplies a username and a password in order to log in:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> LoginsController <span style="color: #990000">&lt;</span> ApplicationController
+
+ verify <span style="color: #990000">:</span>params <span style="color: #990000">=&gt;</span> <span style="color: #990000">[:</span>username<span style="color: #990000">,</span> <span style="color: #990000">:</span>password<span style="color: #990000">],</span>
+ <span style="color: #990000">:</span>render <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">{</span><span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"new"</span><span style="color: #FF0000">}</span><span style="color: #990000">,</span>
+ <span style="color: #990000">:</span>add_flash <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">{</span><span style="color: #990000">:</span>error <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"Username and password required to log in"</span><span style="color: #FF0000">}</span>
+
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> create
+ <span style="color: #009900">@user</span> <span style="color: #990000">=</span> User<span style="color: #990000">.</span>authenticate<span style="color: #990000">(</span>params<span style="color: #990000">[:</span>username<span style="color: #990000">],</span> params<span style="color: #990000">[:</span>password<span style="color: #990000">])</span>
+ <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #009900">@user</span>
+ flash<span style="color: #990000">[:</span>notice<span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"You're logged in"</span>
+ redirect_to root_url
+ <span style="font-weight: bold"><span style="color: #0000FF">else</span></span>
+ render <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"new"</span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<div class="para"><p>Now the <tt>create</tt> action won't run unless the "username" and "password" parameters are present, and if they're not, an error message will be added to the flash and the "new" action will be rendered. But there's something rather important missing from the verification above: It will be used for <strong>every</strong> action in LoginsController, which is not what we want. You can limit which actions it will be used for with the <tt>:only</tt> and <tt>:except</tt> options just like a filter:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> LoginsController <span style="color: #990000">&lt;</span> ApplicationController
+
+ verify <span style="color: #990000">:</span>params <span style="color: #990000">=&gt;</span> <span style="color: #990000">[:</span>username<span style="color: #990000">,</span> <span style="color: #990000">:</span>password<span style="color: #990000">],</span>
+ <span style="color: #990000">:</span>render <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">{</span><span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"new"</span><span style="color: #FF0000">}</span><span style="color: #990000">,</span>
+ <span style="color: #990000">:</span>add_flash <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">{</span><span style="color: #990000">:</span>error <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"Username and password required to log in"</span><span style="color: #FF0000">}</span><span style="color: #990000">,</span>
+ <span style="color: #990000">:</span>only <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>create <span style="font-style: italic"><span style="color: #9A1900">#Only run this verification for the "create" action</span></span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+</div>
+<h2 id="_the_request_and_response_objects">8. The request and response objects</h2>
+<div class="sectionbody">
+<div class="para"><p>In every controller there are two accessor methods pointing to the request and the response objects associated with the request cycle that is currently in execution. The <tt>request</tt> method contains an instance of <a href="http://api.rubyonrails.org/classes/ActionController/AbstractRequest.html">AbstractRequest</a> and the <tt>response</tt> method contains the <a href="http://github.com/rails/rails/tree/master/actionpack/lib/action_controller/response.rb">response object</a> representing what is going to be sent back to the client.</p></div>
+<h3 id="_the_request">8.1. The request</h3>
+<div class="para"><p>The request object contains a lot of useful information about the request coming in from the client. To get a full list of the available methods, refer to the <a href="http://api.rubyonrails.org/classes/ActionController/AbstractRequest.html">API documentation</a>.</p></div>
+<div class="ilist"><ul>
+<li>
+<p>
+host - The hostname used for this request.
+</p>
+</li>
+<li>
+<p>
+domain - The hostname without the first part (usually "www").
+</p>
+</li>
+<li>
+<p>
+format - The content type requested by the client.
+</p>
+</li>
+<li>
+<p>
+method - The HTTP method used for the request.
+</p>
+</li>
+<li>
+<p>
+get?, post?, put?, delete?, head? - Returns true if the HTTP method is get/post/put/delete/head.
+</p>
+</li>
+<li>
+<p>
+headers - Returns a hash containing the headers associated with the request.
+</p>
+</li>
+<li>
+<p>
+port - The port number (integer) used for the request.
+</p>
+</li>
+<li>
+<p>
+protocol - The protocol used for the request.
+</p>
+</li>
+<li>
+<p>
+query_string - The query string part of the URL - everything after "?".
+</p>
+</li>
+<li>
+<p>
+remote_ip - The IP address of the client.
+</p>
+</li>
+<li>
+<p>
+url - The entire URL used for the request.
+</p>
+</li>
+</ul></div>
+<h4 id="_path_parameters_query_parameters_and_request_parameters">8.1.1. path_parameters, query_parameters and request_parameters</h4>
+<div class="para"><p>TODO: Does this belong here?</p></div>
+<div class="para"><p>Rails collects all of the parameters sent along with the request in the <tt>params</tt> hash, whether they are sent as part of the query string or the post body. The request object has three accessors that give you access to these parameters depending on where they came from. The <tt>query_parameters</tt> hash contains parameters that were sent as part of the query string while the <tt>request_parameters</tt> hash contains parameters sent as part of the post body. The <tt>path_parameters</tt> hash contains parameters that were recognised by the routing as being part of the path leading to this particular controller and action.</p></div>
+<h3 id="_the_response">8.2. The response</h3>
+<div class="para"><p>The response objects is not usually used directly, but is built up during the execution of the action and rendering of the data that is being sent back to the user, but sometimes - like in an after filter - it can be useful to access the response directly. Some of these accessor methods also have setters, allowing you to change their values.</p></div>
+<div class="ilist"><ul>
+<li>
+<p>
+body - This is the string of data being sent back to the client. This is most often HTML.
+</p>
+</li>
+<li>
+<p>
+status - The HTTP status code for the response, like 200 for a successful request or 404 for file not found.
+</p>
+</li>
+<li>
+<p>
+location - The URL the client is being redirected to, if any.
+</p>
+</li>
+<li>
+<p>
+content_type - The content type of the response.
+</p>
+</li>
+<li>
+<p>
+charset - The character set being used for the response. Default is "utf8".
+</p>
+</li>
+</ul></div>
+</div>
+<h2 id="_http_basic_authentication">9. HTTP Basic Authentication</h2>
+<div class="sectionbody">
+<div class="para"><p>Rails comes with built-in HTTP Basic authentication. This is an authentication scheme that is supported by the majority of browsers and other HTTP clients. As an example, we will create an administration section which will only be available by entering a username and a password into the browser's HTTP Basic dialog window. Using the built-in authentication is quite easy and only requires you to use one method, <a href="http://api.rubyonrails.org/classes/ActionController/HttpAuthentication/Basic/ControllerMethods.html#M000610">authenticate_or_request_with_http_basic</a>.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> AdminController <span style="color: #990000">&lt;</span> ApplicationController
+
+ USERNAME<span style="color: #990000">,</span> PASSWORD <span style="color: #990000">=</span> <span style="color: #FF0000">"humbaba"</span><span style="color: #990000">,</span> <span style="color: #FF0000">"f59a4805511bf4bb61978445a5380c6c"</span>
+
+ before_filter <span style="color: #990000">:</span>authenticate
+
+private
+
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> authenticate
+ authenticate_or_request_with_http_basic <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>username<span style="color: #990000">,</span> password<span style="color: #990000">|</span>
+ username <span style="color: #990000">==</span> USERNAME <span style="color: #990000">&amp;&amp;</span> Digest<span style="color: #990000">::</span>MD5<span style="color: #990000">.</span>hexdigest<span style="color: #990000">(</span>password<span style="color: #990000">)</span> <span style="color: #990000">==</span> PASSWORD
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<div class="para"><p>With this in place, you can create namespaced controllers that inherit from AdminController. The before filter will thus be run for all actions in those controllers, protecting them with HTTP Basic authentication.</p></div>
+</div>
+<h2 id="_streaming_and_file_downloads">10. Streaming and file downloads</h2>
+<div class="sectionbody">
+<div class="para"><p>Sometimes you may want to send a file to the user instead of rendering an HTML page. All controllers in Rails have the <a href="http://api.rubyonrails.org/classes/ActionController/Streaming.html#M000624">send_data</a> and the <a href="http://api.rubyonrails.org/classes/ActionController/Streaming.html#M000623">send_file</a> methods, that will both stream data to the client. <tt>send_file</tt> is a convenience method which lets you provide the name of a file on the disk and it will stream the contents of that file for you.</p></div>
+<div class="para"><p>To stream data to the client, use <tt>send_data</tt>:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000080">require</span></span> <span style="color: #FF0000">"prawn"</span>
+<span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ClientsController <span style="color: #990000">&lt;</span> ApplicationController
+
+ <span style="font-style: italic"><span style="color: #9A1900"># Generate a PDF document with information on the client and return it.</span></span>
+ <span style="font-style: italic"><span style="color: #9A1900"># The user will get the PDF as a file download.</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> download_pdf
+ client <span style="color: #990000">=</span> Client<span style="color: #990000">.</span>find<span style="color: #990000">(</span>params<span style="color: #990000">[:</span>id<span style="color: #990000">])</span>
+ send_data<span style="color: #990000">(</span>generate_pdf<span style="color: #990000">,</span> <span style="color: #990000">:</span>filename <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"#{client.name}.pdf"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>type <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"application/pdf"</span><span style="color: #990000">)</span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+private
+
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> generate_pdf<span style="color: #990000">(</span>client<span style="color: #990000">)</span>
+ Prawn<span style="color: #990000">::</span>Document<span style="color: #990000">.</span>new <span style="font-weight: bold"><span style="color: #0000FF">do</span></span>
+ text client<span style="color: #990000">.</span>name<span style="color: #990000">,</span> <span style="color: #990000">:</span>align <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>center
+ text <span style="color: #FF0000">"Address: #{client.address}"</span>
+ text <span style="color: #FF0000">"Email: #{client.email}"</span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span>render
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<div class="para"><p>The <tt>download_pdf</tt> action in the example above will call a private method which actually generates the file (a PDF document) and returns it as a string. This string will then be streamed to the client as a file download and a filename will be suggested to the user. Sometimes when streaming files to the user, you may not want them to download the file. Take images, for example, which can be embedded into HTML pages. To tell the browser a file is not meant to be downloaded, you can set the <tt>:disposition</tt> option to "inline". The opposite and default value for this option is "attachment".</p></div>
+<h3 id="_sending_files">10.1. Sending files</h3>
+<div class="para"><p>If you want to send a file that already exists on disk, use the <tt>send_file</tt> method. This is usually not recommended, but can be useful if you want to perform some authentication before letting the user download the file.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ClientsController <span style="color: #990000">&lt;</span> ApplicationController
+
+ <span style="font-style: italic"><span style="color: #9A1900"># Stream a file that has already been generated and stored on disk</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> download_pdf
+ client <span style="color: #990000">=</span> Client<span style="color: #990000">.</span>find<span style="color: #990000">(</span>params<span style="color: #990000">[:</span>id<span style="color: #990000">])</span>
+ send_data<span style="color: #990000">(</span><span style="color: #FF0000">"#{RAILS_ROOT}/files/clients/#{client.id}.pdf"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>filename <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"#{client.name}.pdf"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>type <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"application/pdf"</span><span style="color: #990000">)</span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<div class="para"><p>This will read and stream the file 4Kb at the time, avoiding loading the entire file into memory at once. You can turn off streaming with the <tt>stream</tt> option or adjust the block size with the <tt>buffer_size</tt> option.</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/warning.png" alt="Warning" />
+</td>
+<td class="content">Be careful when using (or just don't use) "outside" data (params, cookies, etc) to locate the file on disk, as this is a security risk as someone could gain access to files they are not meant to have access to.</td>
+</tr></table>
+</div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/tip.png" alt="Tip" />
+</td>
+<td class="content">It is not recommended that you stream static files through Rails if you can instead keep them in a public folder on your web server. It is much more efficient to let the user download the file directly using Apache or another web server, keeping the request from unnecessarily going through the whole Rails stack.</td>
+</tr></table>
+</div>
+<h3 id="_restful_downloads">10.2. RESTful downloads</h3>
+<div class="para"><p>While <tt>send_data</tt> works just fine, if you are creating a RESTful application having separate actions for file downloads is usually not necessary. In REST terminology, the PDF file from the example above can be considered just another representation of the client resource. Rails provides an easy and quite sleek way of doing "RESTful downloads". Let's try to rewrite the example so that the PDF download is a part of the <tt>show</tt> action:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ClientsController <span style="color: #990000">&lt;</span> ApplicationController
+
+ <span style="font-style: italic"><span style="color: #9A1900"># The user can request to receive this resource as HTML or PDF.</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> show
+ <span style="color: #009900">@client</span> <span style="color: #990000">=</span> Client<span style="color: #990000">.</span>find<span style="color: #990000">(</span>params<span style="color: #990000">[:</span>id<span style="color: #990000">])</span>
+
+ respond_to <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>format<span style="color: #990000">|</span>
+ format<span style="color: #990000">.</span>html
+ format<span style="color: #990000">.</span>pdf<span style="color: #FF0000">{</span> render <span style="color: #990000">:</span>pdf <span style="color: #990000">=&gt;</span> generate_pdf<span style="color: #990000">(</span><span style="color: #009900">@client</span><span style="color: #990000">)</span> <span style="color: #FF0000">}</span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<div class="para"><p>In order for this example to work, we have to add the PDF MIME type to Rails. This can be done by adding the following line to the file <tt>config/initializers/mime_types.rb</tt>:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>Mime<span style="color: #990000">::</span>Type<span style="color: #990000">.</span>register <span style="color: #FF0000">"application/pdf"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>pdf
+</tt></pre></div></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/note.png" alt="Note" />
+</td>
+<td class="content">Configuration files are not reloaded on each request, so you have to restart the server in order for their changes to take effect.</td>
+</tr></table>
+</div>
+<div class="para"><p>Now the user can request to get a PDF version of a client just by adding ".pdf" to the URL:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>GET /clients/1.pdf</tt></pre>
+</div></div>
+</div>
+<h2 id="_parameter_filtering">11. Parameter filtering</h2>
+<div class="sectionbody">
+<div class="para"><p>Rails keeps a log file for each environment (development, test and production) in the "log" folder. These are extremely useful when debugging what's actually going on in your application, but in a live application you may not want every bit of information to be stored in the log file. The <a href="http://api.rubyonrails.org/classes/ActionController/Base.html#M000837">filter_parameter_logging</a> method can be used to filter out sensitive information from the log. It works by replacing certain keys in the <tt>params</tt> hash with "[FILTERED]" as they are written to the log. As an example, let's see how to filter all parameters with keys that include "password":</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ApplicationController <span style="color: #990000">&lt;</span> ActionController<span style="color: #990000">::</span>Base
+
+ filter_parameter_logging <span style="color: #990000">:</span>password
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<div class="para"><p>The method works recursively through all levels of the params hash and takes an optional second parameter which is used as the replacement string if present. It can also take a block which receives each key in return and replaces those for which the block returns true.</p></div>
+</div>
+<h2 id="_rescue">12. Rescue</h2>
+<div class="sectionbody">
+<div class="para"><p>Most likely your application is going to contain bugs or otherwise throw an exception that needs to be handled. For example, if the user follows a link to a resource that no longer exists in the database, Active Record will throw the ActiveRecord::RecordNotFound exception. Rails' default exception handling displays a 500 Server Error message for all exceptions. If the request was made locally, a nice traceback and some added information gets displayed so you can figure out what went wrong and deal with it. If the request was remote Rails will just display a simple "500 Server Error" message to the user, or a "404 Not Found" if there was a routing error or a record could not be found. Sometimes you might want to customize how these errors are caught and how they're displayed to the user. There are several levels of exception handling available in a Rails application:</p></div>
+<h3 id="_the_default_500_and_404_templates">12.1. The default 500 and 404 templates</h3>
+<div class="para"><p>By default a production application will render either a 404 or a 500 error message. These messages are contained in static HTML files in the <tt>public</tt> folder, in <tt>404.html</tt> and <tt>500.html</tt> respectively. You can customize these files to add some extra information and layout, but remember that they are static; i.e. you can't use RHTML or layouts in them, just plain HTML.</p></div>
+<h3 id="_tt_rescue_from_tt">12.2. <tt>rescue_from</tt></h3>
+<div class="para"><p>If you want to do something a bit more elaborate when catching errors, you can use <a href=":http://api.rubyonrails.org/classes/ActionController/Rescue/ClassMethods.html#M000620">rescue_from</a>, which handles exceptions of a certain type (or multiple types) in an entire controller and its subclasses. When an exception occurs which is caught by a rescue_from directive, the exception object is passed to the handler. The handler can be a method or a Proc object passed to the <tt>:with</tt> option. You can also use a block directly instead of an explicit Proc object.</p></div>
+<div class="para"><p>Let's see how we can use rescue_from to intercept all ActiveRecord::RecordNotFound errors and do something with them.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ApplicationController <span style="color: #990000">&lt;</span> ActionController<span style="color: #990000">::</span>Base
+
+ rescue_from ActiveRecord<span style="color: #990000">::</span>RecordNotFound<span style="color: #990000">,</span> <span style="color: #990000">:</span>with <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>record_not_found
+
+private
+
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> record_not_found
+ render <span style="color: #990000">:</span>text <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"404 Not Found"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>status <span style="color: #990000">=&gt;</span> <span style="color: #993399">404</span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<div class="para"><p>Of course, this example is anything but elaborate and doesn't improve the default exception handling at all, but once you can catch all those exceptions you're free to do whatever you want with them. For example, you could create custom exception classes that will be thrown when a user doesn't have access to a certain section of your application:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ApplicationController <span style="color: #990000">&lt;</span> ActionController<span style="color: #990000">::</span>Base
+
+ rescue_from User<span style="color: #990000">::</span>NotAuthorized<span style="color: #990000">,</span> <span style="color: #990000">:</span>with <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>user_not_authorized
+
+private
+
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> user_not_authorized
+ flash<span style="color: #990000">[:</span>error<span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"You don't have access to this section."</span>
+ redirect_to <span style="color: #990000">:</span>back
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ClientsController <span style="color: #990000">&lt;</span> ApplicationController
+
+ <span style="font-style: italic"><span style="color: #9A1900"># Check that the user has the right authorization to access clients.</span></span>
+ before_filter <span style="color: #990000">:</span>check_authorization
+
+ <span style="font-style: italic"><span style="color: #9A1900"># Note how the actions don't have to worry about all the auth stuff.</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> edit
+ <span style="color: #009900">@client</span> <span style="color: #990000">=</span> Client<span style="color: #990000">.</span>find<span style="color: #990000">(</span>params<span style="color: #990000">[:</span>id<span style="color: #990000">])</span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+private
+
+ <span style="font-style: italic"><span style="color: #9A1900"># If the user is not authorized, just throw the exception.</span></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> check_authorization
+ <span style="font-weight: bold"><span style="color: #0000FF">raise</span></span> User<span style="color: #990000">::</span>NotAuthorized <span style="font-weight: bold"><span style="color: #0000FF">unless</span></span> current_user<span style="color: #990000">.</span>admin?
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/note.png" alt="Note" />
+</td>
+<td class="content">Certain exceptions are only rescuable from the ApplicationController class, as they are raised before the controller gets initialized and the action gets executed. See Pratik Naik's <a href="http://m.onkey.org/2008/7/20/rescue-from-dispatching">article</a> on the subject for more information.</td>
+</tr></table>
+</div>
+</div>
+
+ </div>
+ </div>
+</body>
+</html>
View
2,577 railties/doc/guides/html/association_basics.html
2,577 additions, 0 deletions not shown
View
227 railties/doc/guides/html/authors.html
@@ -0,0 +1,227 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+ <title>About the Authors</title>
+ <!--[if lt IE 8]>
+ <script src="http://ie7-js.googlecode.com/svn/version/2.0(beta3)/IE8.js" type="text/javascript"></script>
+ <![endif]-->
+ <link href="stylesheets/base.css" media="screen" rel="Stylesheet" type="text/css" />
+ <link href="stylesheets/forms.css" media="screen" rel="Stylesheet" type="text/css" />
+ <link href="stylesheets/more.css" media="screen" rel="Stylesheet" type="text/css" />
+ <style type="text/css">
+ div#container {
+ max-width: 900px;
+ padding-bottom: 3em;
+}
+
+div#content {
+ margin-left: 200px;
+}
+
+div#container.notoc {
+ max-width: 600px;
+}
+
+.notoc div#content {
+ margin-left: 0;
+}
+
+pre {
+ line-height: 1.4em;
+}
+
+#content p tt {
+ background: #eeeeee;
+ border: solid 1px #cccccc;
+ padding: 3px;
+}
+
+dt {
+ font-weight: bold;
+}
+
+#content dt tt {
+ font-size: 10pt;
+}
+
+dd {
+ margin-left: 3em;
+}
+
+#content dt tt, #content pre tt {
+ background: none;
+ padding: 0;
+ border: 0;
+}
+
+#content .olist ol {
+ margin-left: 2em;
+}
+
+#header {
+ position: relative;
+ max-width: 840px;
+ margin-left: auto;
+ margin-right: auto;
+}
+
+#header.notoc {
+ max-width: 580px;
+}
+
+#logo {
+ position: absolute;
+ left: 10px;
+ top: 10px;
+ width: 110px;
+ height: 140px;
+}
+
+div#header h1#site_title {
+ background: url('images/ruby_on_rails_by_mike_rundle2.gif') top left no-repeat;
+ position: absolute;
+ width: 392px;
+ height: 55px;
+ left: 145px;
+ top: 20px;
+ margin: 0;
+ padding: 0;
+}
+
+#site_title span {
+ display: none;
+}
+
+#site_title_tagline {
+ display: none;
+}
+
+ul#navMain {
+