Improve documentation for ActionController::Streaming. Document 'render :text => proc { ... }' as a way to stream on-the-fly generated data to the browser.
This commit is contained in:
parent
659ee09e9a
commit
cce017bed5
@ -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!") }
|
||||
|
@ -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)
|
||||
|
Loading…
Reference in New Issue
Block a user