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)"
|
# # placed in "app/views/layouts/special.r(html|xml)"
|
||||||
# render :text => "Hi there!", :layout => "special"
|
# 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
|
# === Streaming data and/or controlling the page generation
|
||||||
# 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.
|
# 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!"
|
# # Renders "Hello from code!"
|
||||||
# render :text => proc { |response, output| output.write("Hello from code!") }
|
# render :text => proc { |response, output| output.write("Hello from code!") }
|
||||||
|
@ -1,5 +1,6 @@
|
|||||||
module ActionController #:nodoc:
|
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
|
module Streaming
|
||||||
DEFAULT_SEND_FILE_OPTIONS = {
|
DEFAULT_SEND_FILE_OPTIONS = {
|
||||||
:type => 'application/octet-stream'.freeze,
|
:type => 'application/octet-stream'.freeze,
|
||||||
@ -103,8 +104,11 @@ def send_file(path, options = {}) #:doc:
|
|||||||
end
|
end
|
||||||
end
|
end
|
||||||
|
|
||||||
# Send binary data to the user as a file download. May set content type, apparent file name,
|
# Sends the given binary data to the browser. This method is similar to
|
||||||
# and specify whether to show data inline or download as an attachment.
|
# <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:
|
# Options:
|
||||||
# * <tt>:filename</tt> - suggests a filename for the browser to use.
|
# * <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'
|
# send_data image.data, :type => image.content_type, :disposition => 'inline'
|
||||||
#
|
#
|
||||||
# See +send_file+ for more information on HTTP Content-* headers and caching.
|
# 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:
|
def send_data(data, options = {}) #:doc:
|
||||||
logger.info "Sending data #{options[:filename]}" if logger
|
logger.info "Sending data #{options[:filename]}" if logger
|
||||||
send_file_headers! options.merge(:length => data.size)
|
send_file_headers! options.merge(:length => data.size)
|
||||||
|
Loading…
Reference in New Issue
Block a user