upload_progress_helper.rb
上传用户:netsea168
上传日期:2022-07-22
资源大小:4652k
文件大小:17k
源码类别:

Ajax

开发平台:

Others

  1. module UploadProgress
  2.   # Provides a set of methods to be used in your views to help with the
  3.   # rendering of Ajax enabled status updating during a multipart upload.
  4.   #
  5.   # The basic mechanism for upload progress is that the form will post to a
  6.   # hidden <iframe> element, then poll a status action that will replace the
  7.   # contents of a status container.  Client Javascript hooks are provided for
  8.   # +begin+ and +finish+ of the update.
  9.   #
  10.   # If you wish to have a DTD that will validate this page, use XHTML
  11.   # Transitional because this DTD supports the <iframe> element.
  12.   #
  13.   # == Typical usage
  14.   #
  15.   # In your upload view:
  16.   #
  17.   #   <%= form_tag_with_upload_progress({ :action => 'create' }) %>
  18.   #     <%= file_field "document", "file" %>
  19.   #     <%= submit_tag "Upload" %>
  20.   #     <%= upload_status_tag %>
  21.   #   <%= end_form_tag %>
  22.   #
  23.   # In your controller:
  24.   #
  25.   #   class DocumentController < ApplicationController   
  26.   #     upload_status_for  :create
  27.   #     
  28.   #     def create
  29.   #       # ... Your document creation action
  30.   #     end
  31.   #   end
  32.   #   
  33.   # == Javascript callback on begin and finished
  34.   #
  35.   # In your upload view:
  36.   #
  37.   #   <%= form_tag_with_upload_progress({ :action => 'create' }, {
  38.   #       :begin => "alert('upload beginning'), 
  39.   #       :finish => "alert('upload finished')}) %>
  40.   #     <%= file_field "document", "file" %>
  41.   #     <%= submit_tag "Upload" %>
  42.   #     <%= upload_status_tag %>
  43.   #   <%= end_form_tag %>
  44.   #
  45.   #
  46.   # == CSS Styling of the status text and progress bar
  47.   #
  48.   # See +upload_status_text_tag+ and +upload_status_progress_bar_tag+ for references
  49.   # of the IDs and CSS classes used.
  50.   #
  51.   # Default styling is included with the scaffolding CSS.
  52.   module UploadProgressHelper
  53.     unless const_defined? :FREQUENCY
  54.       # Default number of seconds between client updates
  55.       FREQUENCY = 2.0 
  56.       # Factor to decrease the frequency when the +upload_status+ action returns the same results
  57.       # To disable update decay, set this constant to +false+
  58.       FREQUENCY_DECAY = 1.8
  59.     end
  60.     
  61.     # Contains a hash of status messages used for localization of
  62.     # +upload_progress_status+ and +upload_progress_text+.  Each string is
  63.     # evaluated in the helper method context so you can include your own 
  64.     # calculations and string iterpolations.
  65.     #
  66.     # The following keys are defined:
  67.     #
  68.     # <tt>:begin</tt>::      Displayed before the first byte is received on the server
  69.     # <tt>:update</tt>::     Contains a human representation of the upload progress
  70.     # <tt>:finish</tt>::     Displayed when the file upload is complete, before the action has completed.  If you are performing extra activity in your action such as processing of the upload, then inform the user of what you are doing by setting +upload_progress.message+
  71.     #
  72.     @@default_messages = {
  73.       :begin => '"Upload starting..."',
  74.       :update => '"#{human_size(upload_progress.received_bytes)} of #{human_size(upload_progress.total_bytes)} at #{human_size(upload_progress.bitrate)}/s; #{distance_of_time_in_words(0,upload_progress.remaining_seconds,true)} remaining"',
  75.       :finish => 'upload_progress.message.blank? ? "Upload finished." : upload_progress.message',
  76.     }
  77.     # Creates a form tag and hidden <iframe> necessary for the upload progress
  78.     # status messages to be displayed in a designated +div+ on your page.
  79.     #
  80.     # == Initializations
  81.     #
  82.     # When the upload starts, the content created by +upload_status_tag+ will be filled out with
  83.     # "Upload starting...".  When the upload is finished, "Upload finished." will be used.  Every
  84.     # update inbetween the begin and finish events will be determined by the server +upload_status+
  85.     # action.  Doing this automatically means that the user can use the same form to upload multiple
  86.     # files without refreshing page while still displaying a reasonable progress.
  87.     #
  88.     # == Upload IDs
  89.     #
  90.     # For the view and the controller to know about the same upload they must share
  91.     # a common +upload_id+.  +form_tag_with_upload_progress+ prepares the next available 
  92.     # +upload_id+ when called.  There are other methods which use the +upload_id+ so the 
  93.     # order in which you include your content is important.  Any content that depends on the 
  94.     # +upload_id+ will use the one defined +form_tag_with_upload_progress+
  95.     # otherwise you will need to explicitly declare the +upload_id+ shared among
  96.     # your progress elements.
  97.     #
  98.     # Status container after the form:
  99.     #
  100.     #   <%= form_tag_with_upload_progress %>
  101.     #   <%= end_form_tag %>
  102.     #
  103.     #   <%= upload_status_tag %>
  104.     #
  105.     # Status container before form:
  106.     #
  107.     #   <% my_upload_id = next_upload_id %>
  108.     #
  109.     #   <%= upload_status_tag %>
  110.     #
  111.     #   <%= form_tag_with_upload_progress :upload_id => my_upload_id %>
  112.     #   <%= end_form_tag %>
  113.     #
  114.     # It is recommended that the helpers manage the +upload_id+ parameter.
  115.     #
  116.     # == Options
  117.     #
  118.     # +form_tag_with_upload_progress+ uses similar options as +form_tag+
  119.     # yet accepts another hash for the options used for the +upload_status+ action.
  120.     #
  121.     # <tt>url_for_options</tt>:: The same options used by +form_tag+ including:
  122.     # <tt>:upload_id</tt>:: the upload id used to uniquely identify this upload
  123.     #
  124.     # <tt>options</tt>:: similar options to +form_tag+ including:
  125.     # <tt>:begin</tt>::   Javascript code that executes before the first status update occurs.
  126.     # <tt>:finish</tt>::  Javascript code that executes after the action that receives the post returns.
  127.     # <tt>:frequency</tt>:: number of seconds between polls to the upload status action.
  128.     #
  129.     # <tt>status_url_for_options</tt>:: options passed to +url_for+ to build the url
  130.     # for the upload status action.
  131.     # <tt>:controller</tt>::  defines the controller to be used for a custom update status action
  132.     # <tt>:action</tt>::      defines the action to be used for a custom update status action
  133.     #
  134.     # Parameters passed to the action defined by status_url_for_options
  135.     #
  136.     # <tt>:upload_id</tt>::   the upload_id automatically generated by +form_tag_with_upload_progress+ or the user defined id passed to this method.
  137.     #   
  138.     def form_tag_with_upload_progress(url_for_options = {}, options = {}, status_url_for_options = {}, *parameters_for_url_method)
  139.       
  140.       ## Setup the action URL and the server-side upload_status action for
  141.       ## polling of status during the upload
  142.       options = options.dup
  143.       upload_id = url_for_options.delete(:upload_id) || next_upload_id
  144.       upload_action_url = url_for(url_for_options)
  145.       if status_url_for_options.is_a? Hash
  146.         status_url_for_options = status_url_for_options.merge({
  147.           :action => 'upload_status', 
  148.           :upload_id => upload_id})
  149.       end
  150.       status_url = url_for(status_url_for_options)
  151.       
  152.       ## Prepare the form options.  Dynamically change the target and URL to enable the status
  153.       ## updating only if javascript is enabled, otherwise perform the form submission in the same 
  154.       ## frame.
  155.       
  156.       upload_target = options[:target] || upload_target_id
  157.       upload_id_param = "#{upload_action_url.include?('?') ? '&' : '?'}upload_id=#{upload_id}"
  158.       
  159.       ## Externally :begin and :finish are the entry and exit points
  160.       ## Internally, :finish is called :complete
  161.       js_options = {
  162.         :decay => options[:decay] || FREQUENCY_DECAY,
  163.         :frequency => options[:frequency] || FREQUENCY,
  164.       }
  165.       updater_options = '{' + js_options.map {|k, v| "#{k}:#{v}"}.sort.join(',') + '}'
  166.       ## Finish off the updating by forcing the progress bar to 100% and status text because the
  167.       ## results of the post may load and finish in the IFRAME before the last status update
  168.       ## is loaded. 
  169.       options[:complete] = "$('#{status_tag_id}').innerHTML='#{escape_javascript upload_progress_text(:finish)}';"
  170.       options[:complete] << "#{upload_progress_update_bar_js(100)};"
  171.       options[:complete] << "#{upload_update_object} = null"
  172.       options[:complete] = "#{options[:complete]}; #{options[:finish]}" if options[:finish]
  173.       options[:script] = true
  174.       ## Prepare the periodic updater, clearing any previous updater
  175.       updater = "if (#{upload_update_object}) { #{upload_update_object}.stop(); }"
  176.       updater << "#{upload_update_object} = new Ajax.PeriodicalUpdater('#{status_tag_id}',"
  177.       updater << "'#{status_url}', Object.extend(#{options_for_ajax(options)},#{updater_options}))"
  178.       updater = "#{options[:begin]}; #{updater}" if options[:begin]
  179.       updater = "#{upload_progress_update_bar_js(0)}; #{updater}"
  180.       updater = "$('#{status_tag_id}').innerHTML='#{escape_javascript upload_progress_text(:begin)}'; #{updater}"
  181.       
  182.       ## Touch up the form action and target to use the given target instead of the
  183.       ## default one. Then start the updater
  184.       options[:onsubmit] = "if (this.action.indexOf('upload_id') < 0){ this.action += '#{escape_javascript upload_id_param}'; }"
  185.       options[:onsubmit] << "this.target = '#{escape_javascript upload_target}';"
  186.       options[:onsubmit] << "#{updater}; return true" 
  187.       options[:multipart] = true
  188.       [:begin, :finish, :complete, :frequency, :decay, :script].each { |sym| options.delete(sym) }
  189.       ## Create the tags
  190.       ## If a target for the form is given then avoid creating the hidden IFRAME
  191.       tag = form_tag(upload_action_url, options, *parameters_for_url_method)
  192.       unless options[:target]
  193.         tag << content_tag('iframe', '', { 
  194.           :id => upload_target, 
  195.           :name => upload_target,
  196.           :src => '',
  197.           :style => 'width:0px;height:0px;border:0' 
  198.         })
  199.       end
  200.       tag
  201.     end
  202.     # This method must be called by the action that receives the form post
  203.     # with the +upload_progress+.  By default this method is rendered when
  204.     # the controller declares that the action is the receiver of a 
  205.     # +form_tag_with_upload_progress+ posting.
  206.     #
  207.     # This template will do a javascript redirect to the URL specified in +redirect_to+
  208.     # if this method is called anywhere in the controller action.  When the action
  209.     # performs a redirect, the +finish+ handler will not be called.
  210.     #
  211.     # If there are errors in the action then you should set the controller 
  212.     # instance variable +@errors+.  The +@errors+ object will be
  213.     # converted to a javascript array from +@errors.full_messages+ and
  214.     # passed to the +finish+ handler of +form_tag_with_upload_progress+
  215.     #
  216.     # If no errors have occured, the parameter to the +finish+ handler will
  217.     # be +undefined+.
  218.     #
  219.     # == Example (in view)
  220.     #
  221.     #  <script>
  222.     #   function do_finish(errors) {
  223.     #     if (errors) {
  224.     #       alert(errors);
  225.     #     }
  226.     #   }
  227.     #  </script>
  228.     #
  229.     #  <%= form_tag_with_upload_progress {:action => 'create'}, {finish => 'do_finish(arguments[0])'} %>
  230.     #
  231.     def finish_upload_status(options = {})
  232.       # Always trigger the stop/finish callback
  233.       js = "parent.#{upload_update_object}.stop(#{options[:client_js_argument]});n"
  234.       # Redirect if redirect_to was called in controller
  235.       js << "parent.location.replace('#{escape_javascript options[:redirect_to]}');n" unless options[:redirect_to].blank?
  236.       # Guard against multiple triggers/redirects on back
  237.       js = "if (parent.#{upload_update_object}) { #{js} }n"
  238.       
  239.       content_tag("html", 
  240.         content_tag("head", 
  241.           content_tag("script", "function finish() { #{js} }", 
  242.             {:type => "text/javascript", :language => "javascript"})) + 
  243.         content_tag("body", '', :onload => 'finish()'))
  244.     end
  245.     # Renders the HTML to contain the upload progress bar above the 
  246.     # default messages
  247.     #
  248.     # Use this method to display the upload status after your +form_tag_with_upload_progress+
  249.     def upload_status_tag(content='', options={})
  250.       upload_status_progress_bar_tag + upload_status_text_tag(content, options)
  251.     end
  252.     # Content helper that will create a +div+ with the proper ID and class that
  253.     # will contain the contents returned by the +upload_status+ action.  The container
  254.     # is defined as
  255.     #
  256.     #   <div id="#{status_tag_id}" class="uploadStatus"> </div>
  257.     #
  258.     # Style this container by selecting the +.uploadStatus+ +CSS+ class.
  259.     #
  260.     # The +content+ parameter will be included in the inner most +div+ when 
  261.     # rendered.
  262.     #
  263.     # The +options+ will create attributes on the outer most div.  To use a different
  264.     # +CSS+ class, pass a different class option.
  265.     #
  266.     # Example +CSS+:
  267.     #   .uploadStatus { font-size: 10px; color: grey; }
  268.     #
  269.     def upload_status_text_tag(content=nil, options={})
  270.       content_tag("div", content, {:id => status_tag_id, :class => 'uploadStatus ui-progressbar-value ui-widget-header ui-corner-left'}.merge(options))
  271.     end
  272.     # Content helper that will create the element tree that can be easily styled
  273.     # with +CSS+ to create a progress bar effect.  The containers are defined as:
  274.     #
  275.     #   <div class="progressBar" id="#{progress_bar_id}">
  276.     #     <div class="border">
  277.     #       <div class="background">
  278.     #         <div class="content"> </div>
  279.     #       </div>
  280.     #     </div>
  281.     #   </div>
  282.     # 
  283.     # The +content+ parameter will be included in the inner most +div+ when 
  284.     # rendered.
  285.     #
  286.     # The +options+ will create attributes on the outer most div.  To use a different
  287.     # +CSS+ class, pass a different class option.
  288.     #
  289.     # Example:
  290.     #   <%= upload_status_progress_bar_tag('', {:class => 'progress'}) %>
  291.     #
  292.     # Example +CSS+:
  293.     #
  294.     #   div.progressBar {
  295.     #     margin: 5px;
  296.     #   }
  297.     #
  298.     #   div.progressBar div.border {
  299.     #     background-color: #fff;
  300.     #     border: 1px solid grey;
  301.     #     width: 100%;
  302.     #   }
  303.     #
  304.     #   div.progressBar div.background {
  305.     #     background-color: #333;
  306.     #     height: 18px;
  307.     #     width: 0%;
  308.     #   }
  309.     #
  310.     def upload_status_progress_bar_tag(content='', options={})
  311.       css = [options[:class], 'progressBar'].compact.join(' ')
  312.       content_tag("div", 
  313.         content_tag("div", 
  314.           content_tag("div", 
  315.             content_tag("div", content, :class => 'foreground'),
  316.           :class => 'background'), 
  317.         :class => 'border'), 
  318.       {:id => progress_bar_id}.merge(options).merge({:class => css}))
  319.     end
  320.     # The text and Javascript returned by the default +upload_status+ controller
  321.     # action which will replace the contents of the div created by +upload_status_text_tag+
  322.     # and grow the progress bar background to the appropriate width.
  323.     #
  324.     # See +upload_progress_text+ and +upload_progress_update_bar_js+
  325.     def upload_progress_status
  326.       "#{upload_progress_text}<script>#{upload_progress_update_bar_js}</script>"
  327.     end
  328.     
  329.     # Javascript helper that will create a script that will change the width
  330.     # of the background progress bar container.  Include this in the script
  331.     # portion of your view rendered by your +upload_status+ action to
  332.     # automatically find and update the progress bar.
  333.     #
  334.     # Example (in controller):
  335.     #
  336.     #   def upload_status
  337.     #     render :inline => "<script><%= update_upload_progress_bar_js %></script>", :layout => false
  338.     #   end
  339.     #
  340.     #
  341.     def upload_progress_update_bar_js(percent=nil)
  342.       progress = upload_progress
  343.       percent ||= case 
  344.         when progress.nil? || !progress.started? then 0
  345.         when progress.finished? then 100
  346.         else progress.completed_percent
  347.       end.to_i
  348.       # TODO do animation instead of jumping
  349.       "if($('#{progress_bar_id}')){$('#{progress_bar_id}').firstChild.firstChild.style.width='#{percent}%'}"
  350.     end
  351.     
  352.     # Generates a nicely formatted string of current upload progress for
  353.     # +UploadProgress::Progress+ object +progress+.  Addtionally, it
  354.     # will return "Upload starting..." if progress has not been initialized,
  355.     # "Receiving data..." if there is no received data yet, and "Upload
  356.     # finished" when all data has been sent.
  357.     #
  358.     # You can overload this method to add you own output to the
  359.     #
  360.     # Example return: 223.5 KB of 1.5 MB at 321.2 KB/s; less than 10 seconds
  361.     # remaining
  362.     def upload_progress_text(state=nil)
  363.       eval case 
  364.         when state then @@default_messages[state.to_sym]
  365.         when upload_progress.nil? || !upload_progress.started? then @@default_messages[:begin]
  366.         when upload_progress.finished? then @@default_messages[:finish]
  367.         else @@default_messages[:update]
  368.       end 
  369.     end
  370.     protected
  371.     # Javascript object used to contain the polling methods and keep track of
  372.     # the finished state
  373.     def upload_update_object
  374.       "document.uploadStatus#{current_upload_id}"
  375.     end
  376.     # Element ID of the progress bar
  377.     def progress_bar_id
  378.       "UploadProgressBar#{current_upload_id}"
  379.     end
  380.     # Element ID of the progress status container
  381.     def status_tag_id
  382.       "UploadStatus#{current_upload_id}"
  383.     end
  384.     # Element ID of the target <iframe> used as the target of the form
  385.     def upload_target_id
  386.       "UploadTarget#{current_upload_id}"
  387.     end
  388.   end
  389. end