copyright (c) 2008,2009 Jolyon Terwilliger
requires a web server running PHP 5.2.x with the PHP uploadprogress module compiled in or enabled as a shared object: http://pecl.php.net/package/uploadprogress
Dual licensed under the MIT and GPL licenses:
http://www.opensource.org/licenses/mit-license.php
http://www.gnu.org/licenses/gpl.html
plugin to augment a standard file upload form with transparent background upload and add uploadprogress meter to keep client informed of progress. (see requirements above)
upon application, this plugin checks the target form for an UPLOAD_IDENTIFIER input field. If not found, or empty, a unique 11 digit key is generated randomly by the plugin and inserted as a hidden field UPLOAD_IDENTIFIER. Optionally in this demo, there is server side key generation code commented out (qv.)
After key generation, a trigger event is attached to the form submit event listener. Once the form is submitted, an internal flag is set to prevent future submits until the upload is completed successfully. Then the optional 'start' function is called. Next, a hidden, empty target iframe is created to take the form submit request via target attribute. A timer is created to trigger the uploadprogress update calls, which are called and updated repeatedly until the upload is complete, an error occurs or the 'upload not found' limit has been reached (see parameters). It is recommended to use the 'start' and 'success' events to display appropriate messages to the client while upload is taking place.
A load event is attached to the target iframe which triggers the optional 'success' function, when loading is completed. After which the target iframe is removed from the DOM and the uploadActive flag is reset for the form, allowing subsequent submits.
beware that if you use the 'start' optional function to disable or remove any fields from the form, those fields will NOT be submitted with the data. This may change in a future release.
upload error handling has not been fully tested, and likely has problems - please test using the optional 'failed' function to help troubleshoot any problems you find and send reports or suggestions to me.
The demo files cover most of the options and functionality of the plugin which spans a number of concepts. Please carefully review the entire demo source code and the requirements and demos for the separate PHP uploadprogress plugin before attempting any major modifications.
if the 'debugDisplay' option is set to an existing DOM element, full updateProgress response output will be displayed in the container. Also, the target iframe will be appended to the document directly after the debugDisplay element and not removed when upload is completed.
jQuery('form#upload_form').uploadProgress({ id:'uniqueid' | keyLength:11 });
if no id is passed, a key of keyLength or 11 characters is generated and applied to the target form as a hidden field to key the upload session.
id - default: none - optional. will be generated if omitted.
keyLength - default: 11 - length of UPLOAD_IDENTIFIER hidden input field key to be generated.
dataFormat - default: 'json' - only viable option at this point would be jsonp (qv.)
progressURL - default: none - this is the relative or absolute URL used for the uploadprogress update post request.
updateDelay - default: 1000 - in milliseconds - how long between uploadprogress requests. regardless how low this interval is set, the previous info request must finish before the next will be sent. This is for stability and performance.
notFoundLimit - default: 5 - how many loops to allow any return value of 'error' before exiting with failed status. Sometimes the first uploadprogress request is processed by the webserver before the actual upload has been acknowledged and started in the system, potentially returning an 'upload_id not found' error. This is the threshold value to set for # of error messages to allow before failing the upload.
waitText - default: false - If set, this text will be used replace form submit button value text. Note: a flag is set in within the plugin to prevent double-submit actions on the form. Once submit is completed, the original text is restored for future submits.
debugDisplay - default: none - if set, used as a selector for DOM element to display debug output.
progressDisplay - default: .upload-progress - selector for DOM element to target output container ( used to calculate graphic meter constraints and any 'displayFields' specified return data )
progressMeter - default: .meter - selector for DOM element that will be horizontally resized against inner width of progressDisplay (minus 20 pixels padding) as upload progress changes. To disable meter updates, set this to false.
targetUploader - default: jqUploader - id/name for upload target iframe.
fieldPrefix - default: . - selector prefix for jQuery DOM capture of displayField sub-elements of progressDisplay selector.
displayFields - default (Array): ['est_sec'] - array of fields to parse from return ajax request data and target on to DOM elements prefixed by fieldPrefix. See demo and example php servlet for details.
start - default (Function): empty - function to run at beginning of submit request, prior to actual upload submit.
success - default (Function): empty - function to run upon successful completion of upload
failed - default (Function): empty - function to run if upload failed
considering moving the trigger event listener from form submit to all input[type=submit] elements and triggering the form submit event from there. There are some advantages on how to set up handler functions, but I haven't figured out a path yet. ideas?
should fix the timer calls to be closed anonymous functions
I wish the PHP uploadprogress plugin would save at least a temporary cache of data per upload_id. This would make closing the process a lot cleaner with more accurate info.
once again, I learned a lot about various browser quirks while developing this project, especially regarding iframes and loading events. I ended up deferring from my original iframe tactic to the target-iframe hack to preserve sanity on all fronts - the original was getting pretty interesting!
uploadprogress Simple Demo Page
uploadprogress Debug Demo Page
Download jquery.uploadprogress.0.3.js full js with comments and documentation
Download all uploadprogress files and demos includes demo PHP servlet with full and minified versions of uploadprogress.
Remember, this is a very experimental plugin. If you have useful suggestions, thoughtful advice or insights for further development, feel free to email me