From 53cd102b39eb62567298430cbd94e40dd78d46a0 Mon Sep 17 00:00:00 2001
From: Pratik Naik <pratiknaik@gmail.com>
Date: Tue, 24 Feb 2009 12:29:25 +0000
Subject: Merge with docrails
---
actionpack/lib/action_controller/base.rb | 34 +++++++++++++++++++++--
actionpack/lib/action_controller/streaming.rb | 14 ++++++++--
actionpack/lib/action_view/helpers/form_helper.rb | 6 ++--
3 files changed, 46 insertions(+), 8 deletions(-)
(limited to 'actionpack/lib')
diff --git a/actionpack/lib/action_controller/base.rb b/actionpack/lib/action_controller/base.rb
index def57a8dd3..1eda6e3f04 100644
--- a/actionpack/lib/action_controller/base.rb
+++ b/actionpack/lib/action_controller/base.rb
@@ -784,9 +784,37 @@ module ActionController #:nodoc:
# # placed in "app/views/layouts/special.r(html|xml)"
# render :text => "Hi there!", :layout => "special"
#
- # The <tt>:text</tt> option can also accept a Proc object, which can be used to manually control the page generation. This should
- # generally be avoided, as it violates the separation between code and content, and because almost everything that can be
- # done with this method can also be done more cleanly using one of the other rendering methods, most notably templates.
+ # === Streaming data and/or controlling the page generation
+ #
+ # The <tt>:text</tt> option can also accept a Proc object, which can be used to:
+ #
+ # 1. stream on-the-fly generated data to the browser. Note that you should
+ # use the methods provided by ActionController::Steaming instead if you
+ # want to stream a buffer or a file.
+ # 2. manually control the page generation. This should generally be avoided,
+ # as it violates the separation between code and content, and because almost
+ # everything that can be done with this method can also be done more cleanly
+ # using one of the other rendering methods, most notably templates.
+ #
+ # Two arguments are passed to the proc, a <tt>response</tt> object and an
+ # <tt>output</tt> object. The response object is equivalent to the return
+ # value of the ActionController::Base#response method, and can be used to
+ # control various things in the HTTP response, such as setting the
+ # Content-Type header. The output object is an writable <tt>IO</tt>-like
+ # object, so one can call <tt>write</tt> and <tt>flush</tt> on it.
+ #
+ # The following example demonstrates how one can stream a large amount of
+ # on-the-fly generated data to the browser:
+ #
+ # # Streams about 180 MB of generated data to the browser.
+ # render :text => proc { |response, output|
+ # 10_000_000.times do |i|
+ # output.write("This is line #{i}\n")
+ # output.flush
+ # end
+ # }
+ #
+ # Another example:
#
# # Renders "Hello from code!"
# render :text => proc { |response, output| output.write("Hello from code!") }
diff --git a/actionpack/lib/action_controller/streaming.rb b/actionpack/lib/action_controller/streaming.rb
index b6a6a2e5db..9f80f48c3d 100644
--- a/actionpack/lib/action_controller/streaming.rb
+++ b/actionpack/lib/action_controller/streaming.rb
@@ -1,5 +1,6 @@
module ActionController #:nodoc:
- # Methods for sending files and streams to the browser instead of rendering.
+ # Methods for sending arbitrary data and for streaming files to the browser,
+ # instead of rendering.
module Streaming
DEFAULT_SEND_FILE_OPTIONS = {
:type => 'application/octet-stream'.freeze,
@@ -103,8 +104,11 @@ module ActionController #:nodoc:
end
end
- # Send binary data to the user as a file download. May set content type, apparent file name,
- # and specify whether to show data inline or download as an attachment.
+ # Sends the given binary data to the browser. This method is similar to
+ # <tt>render :text => data</tt>, but also allows you to specify whether
+ # the browser should display the response as a file attachment (i.e. in a
+ # download dialog) or as inline data. You may also set the content type,
+ # the apparent file name, and other things.
#
# Options:
# * <tt>:filename</tt> - suggests a filename for the browser to use.
@@ -127,6 +131,10 @@ module ActionController #:nodoc:
# send_data image.data, :type => image.content_type, :disposition => 'inline'
#
# See +send_file+ for more information on HTTP Content-* headers and caching.
+ #
+ # <b>Tip:</b> if you want to stream large amounts of on-the-fly generated
+ # data to the browser, then use <tt>render :text => proc { ... }</tt>
+ # instead. See ActionController::Base#render for more information.
def send_data(data, options = {}) #:doc:
logger.info "Sending data #{options[:filename]}" if logger
send_file_headers! options.merge(:length => data.size)
diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb
index 568687e9e0..4fef2b443e 100644
--- a/actionpack/lib/action_view/helpers/form_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_helper.rb
@@ -646,8 +646,10 @@ module ActionView
# Returns a radio button tag for accessing a specified attribute (identified by +method+) on an object
# assigned to the template (identified by +object+). If the current value of +method+ is +tag_value+ the
- # radio button will be checked. Additional options on the input tag can be passed as a
- # hash with +options+.
+ # radio button will be checked.
+ #
+ # To force the radio button to be checked pass <tt>:checked => true</tt> in the
+ # +options+ hash. You may pass HTML options there as well.
#
# ==== Examples
# # Let's say that @post.category returns "rails":
--
cgit v1.2.3