method

form_tag_with_upload_progress

v1.0.0 - Show latest stable - 0 notes - Class: ActionView::Helpers::UploadProgressHelper

1.0.0 (0)
1.1.6
1.2.6
2.0.3
2.1.0
2.2.1
2.3.8
3.0.0
3.0.9
3.1.0
3.2.1
3.2.8
3.2.13
4.0.2
4.1.8
4.2.1
4.2.7
4.2.9
5.0.0.1
5.1.7
5.2.3
6.0.0
6.1.3.1
6.1.7.7
7.0.0
7.1.3.2
What's this?

form_tag_with_upload_progress(url_for_options = {}, options = {}, status_url_for_options = {}, *parameters_for_url_method)

public

Creates a form tag and hidden <iframe> necessary for the upload progress status messages to be displayed in a designated div on your page.

Initializations

When the upload starts, the content created by upload_status_tag will be filled out with "Upload starting…". When the upload is finished, "Upload finished." will be used. Every update inbetween the begin and finish events will be determined by the server upload_status action. Doing this automatically means that the user can use the same form to upload multiple files without refreshing page while still displaying a reasonable progress.

Upload IDs

For the view and the controller to know about the same upload they must share a common upload_id. form_tag_with_upload_progress prepares the next available upload_id when called. There are other methods which use the upload_id so the order in which you include your content is important. Any content that depends on the upload_id will use the one defined form_tag_with_upload_progress otherwise you will need to explicitly declare the upload_id shared among your progress elements.

Status container after the form:

  <%= form_tag_with_upload_progress %>
  <%= end_form_tag %>

  <%= upload_status_tag %>

Status container before form:

  <% my_upload_id = next_upload_id %>

  <%= upload_status_tag %>

  <%= form_tag_with_upload_progress :upload_id => my_upload_id %>
  <%= end_form_tag %>

It is recommended that the helpers manage the upload_id parameter.

Options

form_tag_with_upload_progress uses similar options as form_tag yet accepts another hash for the options used for the upload_status action.

`url_for_options:`	The same options used by `form_tag` including:
`:upload_id:`	the upload id used to uniquely identify this upload
`options:`	similar options to `form_tag` including:
`:begin:`	Javascript code that executes before the first status update occurs.
`:finish:`	Javascript code that executes after the action that receives the post returns.
`:frequency:`	number of seconds between polls to the upload status action.
`status_url_for_options:`	options passed to `url_for` to build the url

for the upload status action.

`:controller:`	defines the controller to be used for a custom update status action
`:action:`	defines the action to be used for a custom update status action

Parameters passed to the action defined by status_url_for_options

:upload_id: the upload_id automatically generated by form_tag_with_upload_progress or the user defined id passed to this method.

Show source

# File actionpack/lib/action_view/helpers/upload_progress_helper.rb, line 149
      def form_tag_with_upload_progress(url_for_options = {}, options = {}, status_url_for_options = {}, *parameters_for_url_method)
        
        ## Setup the action URL and the server-side upload_status action for
        ## polling of status during the upload

        options = options.dup

        upload_id = url_for_options.delete(:upload_id) || next_upload_id
        upload_action_url = url_for(url_for_options)

        if status_url_for_options.is_a? Hash
          status_url_for_options = status_url_for_options.merge({
            :action => 'upload_status', 
            :upload_id => upload_id})
        end

        status_url = url_for(status_url_for_options)
        
        ## Prepare the form options.  Dynamically change the target and URL to enable the status
        ## updating only if javascript is enabled, otherwise perform the form submission in the same 
        ## frame.
        
        upload_target = options[:target] || upload_target_id
        upload_id_param = "#{upload_action_url.include?('?') ? '&' : '?'}upload_id=#{upload_id}"
        
        ## Externally :begin and :finish are the entry and exit points
        ## Internally, :finish is called :complete

        js_options = {
          :decay => options[:decay] || FREQUENCY_DECAY,
          :frequency => options[:frequency] || FREQUENCY,
        }

        updater_options = '{' + js_options.map {|k, v| "#{k}:#{v}"}.sort.join(',') + '}'

        ## Finish off the updating by forcing the progress bar to 100% and status text because the
        ## results of the post may load and finish in the IFRAME before the last status update
        ## is loaded. 

        options[:complete] = "$('#{status_tag_id}').innerHTML='#{escape_javascript upload_progress_text(:finish)}';"
        options[:complete] << "#{upload_progress_update_bar_js(100)};"
        options[:complete] << "#{upload_update_object} = null"
        options[:complete] = "#{options[:complete]}; #{options[:finish]}" if options[:finish]

        options[:script] = true

        ## Prepare the periodic updater, clearing any previous updater

        updater = "if (#{upload_update_object}) { #{upload_update_object}.stop(); }"
        updater << "#{upload_update_object} = new Ajax.PeriodicalUpdater('#{status_tag_id}',"
        updater << "'#{status_url}', Object.extend(#{options_for_ajax(options)},#{updater_options}))"

        updater = "#{options[:begin]}; #{updater}" if options[:begin]
        updater = "#{upload_progress_update_bar_js(0)}; #{updater}"
        updater = "$('#{status_tag_id}').innerHTML='#{escape_javascript upload_progress_text(:begin)}'; #{updater}"
        
        ## Touch up the form action and target to use the given target instead of the
        ## default one. Then start the updater

        options[:onsubmit] = "if (this.action.indexOf('upload_id') < 0){ this.action += '#{escape_javascript upload_id_param}'; }"
        options[:onsubmit] << "this.target = '#{escape_javascript upload_target}';"
        options[:onsubmit] << "#{updater}; return true" 
        options[:multipart] = true

        [:begin, :finish, :complete, :frequency, :decay, :script].each { |sym| options.delete(sym) }

        ## Create the tags
        ## If a target for the form is given then avoid creating the hidden IFRAME

        tag = form_tag(upload_action_url, options, *parameters_for_url_method)

        unless options[:target]
          tag << content_tag('iframe', '', { 
            :id => upload_target, 
            :name => upload_target,
            :src => '',
            :style => 'width:0px;height:0px;border:0' 
          })
        end

        tag
      end

form_tag_with_upload_progress

Related methods

Initializations

Upload IDs

Options

Flowdock - Team Inbox With Chat