Skip to content
Browse files

Improve documentation for ActionController::Streaming. Document 'rend…

…er :text => proc { ... }' as a way to stream on-the-fly generated data to the browser.
  • Loading branch information...
1 parent 659ee09 commit cce017bed56f6b91a4b1a5fe0a81154f378397fc @FooBarWidget FooBarWidget committed Feb 8, 2009
Showing with 42 additions and 6 deletions.
  1. +31 −3 actionpack/lib/action_controller/base.rb
  2. +11 −3 actionpack/lib/action_controller/streaming.rb
View
34 actionpack/lib/action_controller/base.rb
@@ -784,9 +784,37 @@ def append_view_path(path)
# # 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!") }
View
14 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 @@ def send_file(path, options = {}) #:doc:
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 @@ def send_file(path, options = {}) #:doc:
# 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)

0 comments on commit cce017b

Please sign in to comment.
Something went wrong with that request. Please try again.