Other versions:

FancyUpload - Swiff meets Ajax (v3.0)

Project FancyUpload - Swiff meets Ajax Showcase Swiff meets Ajax for powerful and elegant uploads. FancyUpload is a file-input replacement which features an unobtrusive, multiple-file selection menu and queued upload with an animated progress bar. It is easy to setup, is server independent, completely styleable via CSS and XHTML and uses MooTools to work in all modern browsers.


Showcases

Previous Version

If you missed the link above, the previous FancyUpload for MooTools 1.11 is still available including example code and minor updates. It is not maintained anymore.

Features

  • Select and upload multiple files
  • Filter files by type in the select dialog
  • A lot of possible Events to add your own behaviour
  • Show and filter useful file information before the upload starts
  • Limit uploads by file count, type or size
  • Platform and server independent, just needs Flash 9+ (> 95% penetration)
  • Graceful Degradation, since the element is replaced after the Flash is loaded successfully
  • Cancel running uploads, add files during upload
  • Everything is optional, documented and easy editable
  • New in 2.0
    • Get the server response after upload for showing additional informations or previewing the image, etc.
    • Shows the current upload speed and the time left
    • Send additional request data via GET or POST variables
    • Set the filename for the upload request
  • New in 3.0 (Completely rewritten API)
    • Fully Flash 9 and 10 compatible and an additional IFrame-based uploader
    • Browse-button can be an invisible overlay or an interactive image sprite
    • Event based Flash communication, future-proof und more stable
    • File-specific options for setting url, data and method, intelligently merged
    • Append cookies automatically to the request data
    • Relative URLs are converted automatically

Compatibility

Fully compatible with all A-Grade Browsers (Internet Explorer 6+, Opera 9, Firefox 1.5+ and Safari 3+) with Adobe Flash 9 and 10 player.

How to use

The available showcases show off documented code snippets with various use cases.

Documentation

Class: Swiff.Uploader

Extends:
Syntax:
var uploader = new Swiff.Uploader([options]);
Arguments:
  1. options - (object, optional) See options below. Also inherited are all the options from Swiff.

Returns:

  • (object|false) - New Swiff.Uploader instance.
Options:
  • path - (string: defaults to “Swiff.Uploader.swf”) The relative or absolute path to the Flash movie (Swiff.Uploader.swf) on the server
  • height: (number: defaults to 30) Only needed if you use buttonImage, otherwise its handled positioned over the target.
  • width: (number: defaults to 100) Only needed if you use buttonImage, otherwise its handled positioned over the target.
  • typeFilter: (object|string: defaults to null) Key/value pairs are used as filters for the dialog. Possible pair would be 'Images (*.jpg, *.jpeg, *.gif, *.png)': '*.jpg; *.jpeg; *.gif; *.png'.
  • multiple: (boolean: defaults to true) If true, the browse-dialog allows multiple-file selection.
  • queued: (number: defaults to 1) Maximum of currently running files. If this is false, all files are uploaded at once.
  • verbose: (boolean: defaults to false) Debug mode, logs messages and all events from Flash during development (using console.info).
  • target: (element: defaults to null) If given, the browse-element is overlayed with a transparent movie. The Events click/mouseenter/mouseleave/disabled are fired as events on target.
  • zIndex: (number: defaults to 9999) Only used if a target is given, this sets the z-index for the overlay.
  • buttonImage: (string: defaults to null) Sprite for the upload button, has to have 4 states vertically aligned: Normal, hovered, clicked and disabled. Make sure to adapt the options width and height.
  • policyFile: (string: defaults to null) Location the cross-domain policy file. See Flash Security.loadPolicyFile.
  • url: (string: defaults to null) URL to the server-side script (relative URLs are changed automatically to absolute paths).
  • method: (string: defaults to ‘post’) If the method is ‘get’, data is appended as query-string to the URL. The upload will always be a POST request.
  • data: (object|string: defaults to null) Key/data values that are sent with the upload requests.
  • mergeData: (boolean: defaults to true) If true, the data option from uploader and file is merged (prioritised file data).
  • fieldName: (string: defaults to “Filedata”) The key of the uploaded file on your server, similar to name in a file-input. Linux Flash ignores it, better avoid it.
  • fileSizeMin: (number: defaults to 1) Validates the minimal size of a selected file byte.
  • fileSizeMax: (number: defaults to 0) Validates the maximal size of a selected file (official limit is 100 MB for FileReference, I tested up to 2 GB)
  • allowDuplicates: (boolean: defaults to false) Validates that no duplicate files are added.
  • timeLimit: (number: default 30, 0 for linux) Timeout in seconds. If the upload is without progress, it is cancelled and event complete gets fired (with error string timeout). Occurs usually when the server sends an empty response (also on redirects).
  • fileList: (boolean: defaults to false) Validates that no duplicate files are added.
  • fileListMax: (number: defaults to 0) Validates the overall file count.
  • fileListSizeMax: (number: defaults to 0) Validates the overall file size in byte.
  • instantStart: (boolean: defaults to false) If true, the upload starts right after a successful file selection.
  • appendCookieData: (boolean|string: defaults to false) If this is not false, the cookies of the browser are merged into the given options data. If a string is given, it is used as key for the data.
  • fileClass: (class: defaults to Swiff.Uploader.File) An instance of this class is created for every selected file.

The options url, method, data and mergeData are also available in Swiff.Uploader.File. If you don’t set them per-file, they default to the options in your Swiff.Uploader instance. To change them during runtime, simply use setOptions and it does all the magic for you.

Events:
  • load - (function) Function to execute when the Flash movie is initialised.
  • fail - (function) Function to execute when the loading is prevented. First argument is the error type and can be:
    • flash - Flash is not installed or the Flash version did not meet the requirements.
    • blocked - The user has to enable the movie manually because of Flashblock, no refresh required.
    • empty - The Flash movie failed to load, check if the file exists and the path is correct.
    • hidden - Adblock Plus blocks hides the movie, the user has enable it and refresh.
  • start - (function) Function to execute when the upload starts.
  • queue - (function) Function to execute when the queue statistics are updated.
  • complete - (function) Function to execute when all files are uploaded (or stopped).
  • browse - (function) Function to execute when the browse-dialog opens.
  • disabledBrowse - (function) Function to execute when the user tries to open the browse-dialog, but the uploader is disabled.
  • cancel - (function) Function to execute when the user closes the browse-dialog without a selection.
  • select - (function) Function to execute when the user selected files in the dialog. Preferred events are selectSuccess and selectFail!
    1. successFiles - (array|null) Raw file data for successfully added files.
    2. failFiles - (array|null) Raw file data for invalid files that were not added.
  • selectSuccess - (function) Function to execute when files were selected and validated successfully.
    1. successFiles - (array|null) Added file instances (see option fileClass).
  • selectFail - (function) Function to execute when files were selected and failed validation.
    1. failFiles - (array|null) Dismissed file instances (see option fileClass).
  • reposition - (function) Function to execute when reposition method is called on uploader (usually on window-resize).
  • beforeStart - (function) Function to execute when start method is called on uploader.
  • beforeStop - (function) Function to execute when stop method is called on uploader.
  • beforeRemove - (function) Function to execute when remove method is called on uploader.
  • buttonEnter - (function) Function to execute when the mouse enters the browse button.
  • buttonLeave - (function) Function to execute when the mouse leave the browse button.
  • buttonDown - (function) Function to execute when the mouse clicks the browse button.
  • buttonDisable - (function) Function to execute when the script disables the browse button.
  • fileStart - (function) Function to execute when flash initialised the upload for a file.
  • fileStop - (function) Function to execute when a file got stopped manually.
  • fileRequeue - (function) Function to execute when a file got added back to the queue after being stopped or completed.
  • fileOpen - (function) Function to execute when the file is accessed before for upload.
  • fileProgress - (function) Function to execute when the upload reports progress.
  • fileComplete - (function) Function to execute when a file is uploaded or failed with an error.
  • fileRemove - (function) Function to execute when a file got removed.

Every Event starting with file is also called on the Swiff.Uploader.File class, without prepended file.

Swiff.Uploader Method: start

Starts the upload process. Also available in Swiff.Uploader.File.

Swiff.Uploader Method: stop

Stops all running files. Also available in Swiff.Uploader.File.

Swiff.Uploader Method: remove

Remove all files from the list. Also available in Swiff.Uploader.File.

Swiff.Uploader Method: reposition

Updates the position for the movie overlay, if you use option target.

Arguments:
  1. coordinates - (object, optional) New coordinates (left/top/width/height), automatically detected from the current target.
Swiff.Uploader Method: setEnabled

Enables or disables the browse button.

Arguments:
  1. status - (boolean, optional) Toggles the current status if no value if provided, otherwise updates the status to the given value.
Swiff.Uploader Property: target

The target Element from the options, override it if you switch your browser button.

Swiff.Uploader Property: uploading

The number of running uploads.

Swiff.Uploader Property: size

The overall size of all files in the list in byte.

Swiff.Uploader Property: bytesLoaded

The overall loaded size of running and completed files in the list in byte.

Swiff.Uploader Property: bytesLoaded

The overall loaded percentage of running and completed files in the list.

Swiff.Uploader Property: rate

The overall rate of running files in the list in bytes/second.

Class: Swiff.Uploader.File

Mirrors several methods and events from the documentation above. Custom file classes usually extends it and are given to Swiff.Uploader via the fileClass option.

FAQ, Tips, Tricks, Quirks

How do I access the uploaded files?

Every upload, even with multiple files, results in one request. Access the uploaded file via

Filedata is the default value for the option fieldName, so you can change it. The submitted content-type header is always application/octet-stream, so don’t trust it when you validate the file.

Flash-request forgets cookies and session ID

See option appendCookieData. Flash FileReference is not an intelligent upload class, the request will not have the browser cookies, Flash saves his own cookies. When you have sessions, append them as get-data to the the URL (e.g. “upload.php?SESSID=123456789abcdef”). Of course your session-name can be different.

Are cross-domain uploads possible?

For uploading and downloading operations, a SWF file can access files only within its own domain, including any domains that are specified by a cross-domain policy file. If the SWF that is initiating the upload or download doesn’t come from the same domain as the file server, you must put a policy file on the file server. More on security and link to cross-domain policies

FancyUpload does not load, the input element gets not replaced

Check in Firebug in Net/Flash that the SWF file loads correctly. If not double check your given options.

Uploads fail with 404 error code

Check your URL and better use an absolute upload URL.

IE takes the upload url relative to the swf, all other browsers relative to the html/current file. So the best solution is an absolute path for the option url or rather the form action. If you have problems with failed upload and 404 error codes, try an absolute url, in your form-action or url option when creating your FancyUpload instance.

Uploads fail with 406/403 error

From the swfupload documentation (it applies to all Flash scripts depending on FileReference):

If you are using Apache with mod_security this will not work, you need to put the following in your .htaccess file to disable mod_security:

SecFilterEngine Off SecFilterScanPOST Off

Disabling mod_security isn’t allowed on some shared hosts, and only do this if you know what you are doing. This is due to a bug in the way that flash sends the headers back to the server according to the Flash 8 documentation

Uploads fail with 403/500 error

Check your server config, there must be something wrong. Also see 404, double check the upload URL.

Uploads and Basic Authentication

Flash does not care about authenticated Browsers. Firefix/Win/Flash 9 can handle it, IE too, Mac can’t handle it. Anyways, Flash will ask for its own access username and password.

Requirements

It does not depend on any server-side architecture or language.

MooTools JavaScript Framework 1.2

You can include MooTools via Google AJAX Libraries API, follow the link for more information and why it can be good for your site.

Required MooTools Core components:
  • Element.Events
  • Element.Dimensions
  • Fx.Tween
  • Fx.Transitions
  • Selectors
  • JSON
  • Swiff
  • DomReady (facultative)

Don’t use compressed code during development to simplify debugging.

Download

Complete ActionScript/JavaScript source, documentation and showcases are available at github, in my fancyupload repository.

Packages

Single Files

You can contribute by reporting problems and bugs in the issue tracker on github or in the support forum to discuss it.

References

Changelog

3.0 (2009-05-25)
  • Added: Option timeLimit (default 30s, 0 for linux). Prevents frozen upload when server fails, after timeout the upload is cancelled and the complete event fired (with “timeout” error).
  • Added: Option policyFile, custom location for the cross-domain policy.
  • Added: Events beforeStart/Stop/Remove for more control over the upload process (e.g. setting data from inputs).
  • Changed: 1s delay for onFail, prevents failing on slow connections.
  • Fixed: data is not correctly merged between uploader options and file-specific options.
  • Fixed: Removed debugging behaviour on progress bars.
3.0 rc1 (2009-05-05)
  • Added: New showcase attach-a-file including first iteration of the class Attach.
  • Added: New event reposition, fired when the box is moved.
  • Changed: More converted placeholder-units for validation errors.
  • Fixed: remove event did not fire correctly, broke option fileListMax
  • Fixed: Example script.php did not clear log file correctly.
  • Fixed: I really missed a console.log in FancyUpload2.js, sorry!
3.0 rc0 (2009-04-30)
  • Added: Total rewrite of Swiff.Uploader JavaScript and Actionscript
  • Added: Event based interactions from Flash to JS
  • Added: File-based list handling for easy implementation
  • Added: IFrame fallback class Uploader.js, mirroring the Swiff.Uploader API
  • Added: Several new options like appendCookieData, buttonImage and various validations
  • Fixed: All known bugs (case-sensitive typeFilter, sending data, Mac problems, load events, …)
2.0 (2008-12-05)
  • Added: Flash 10 support
  • Added: removeFile now returns the new global progress status, to refresh numbers
  • Fixed: Clickable overlay for Flash 10, define your target element with option “target”
  • Fixed: Encoding problems fixed, JS calls failed due to ExternalInterface bugs (Kudos to SwfUpload for their short and efficient fix)
  • Fixed: Cancelling a running file starts the next file
  • Fixed: Enabled cross domain upload
2.0 beta 4 (2008-05-09)
  • Fixed: Fixed fileUpload to return changed options, fixes overriding options.
2.0 beta 3 (2008-05-06)
  • Added: Optional events for every callback (e.g. onSelect, onComplete, etc.) are added automatically for more control
  • Added: Option limitSize (default false) to limit file size (in bytes) of a single selected file
  • Added: Option limitFiles (default true) to limit queue length, ignores finished files
  • Added: Option allowDuplicates (default false) to disable duplicate files in queue (checking name and size)
  • Added: Option validateFile as custom callback validator (default returns always true). Should return true or false.
  • Added: Optional callbacks for handling the file updates, allowing to control the behaviour and layout of the file elements:
    • fileInvalid: called for invalid files with error stack as 2nd argument
    • fileCreate: creates file element after select (see FancyUpload2::fileCreate for default method)
    • fileUpload: called when file is opened for upload, allows to modify the upload options (data, url, method, fieldName) for every upload.
    • fileComplete: updates the file element to completed state and gets the response (2nd argument) (see FancyUpload2::fileComplete for default method)
    • fileRemove: removes the element (see FancyUpload2::fileRemove for default method)
  • Fixed: callback options are added as events , so they don’t break FancyUpload callbacks
2.0 preview 2 (2008-04-24)
  • Fixed: Removed overflow auto from the lists to fix scrollbars.
  • Fixed: Fixed overall progress file size for removed files.
  • Fixed: New time left calculation, still needs some tweaks for the internal AS3 calculation.
2.0 preview (2008-04-21)

Refactored JS and ActionScript, it is not compatible with previous FancyUpload but a lot better!

  • Added: New Interface using all the new features (will change in the future for easier customization)
  • Added: Get the server response for uploaded files in onComplete, no longer error-catching with header status codes
  • Added: Get the current states of uploads like time left, bytes upload, for the current file and per queue … for supreme progress bars
  • Added: Set POST and GET data for the upload request
  • Added: Set the file-name for the upload request, default Filedata, like before.
  • Added: Set request options for every file, modify upload options with onBeforeOpen
  • Added: New events: onAllSelect, onBeforeOpen and onAllComplete
  • Changed: Update to MooTools 1.2 trunk and the modified Swiff Class
  • Changed: Updated to Flash 9 + ActionScript 3 for a stable API with more features
  • Fixed: Cache bug for IE, thanks to Flash 9
  • Fixed: Scroll into view bug for Firefox, fixed wmode
  • Fixed: Flash 9 works fine on Linux/Firefox
1.0.2 (2008-04-20)
  • Fixed: Fixed IE errors when unloading the page by removing the element in Swiff.Base.js
  • Fixed: Scroll into view bug for Firefox, fixed wmode
1.0.1 (2007-07-04)
  • Added: Events onError and onCancel for files
  • Change: Added better behaviour for onComplete and onAllComplete, now you can trust them
  • Change: Removed internal empty onCancel, since Flash makes it useless and some other clean-ups
  • Fixed: limitFiles works now and allowDuplicates is default true
  • Fixed: Swiff.Uploader.js: Added anti-cache fix for IE and small improvements for parameters
  • Fixed: FancyUpload.js: Fixed options in FancyUpload to work with MooTools 1.2dev
1.0 (2007-05-31)
  • Changed: Added more checks to make SWF-JS communication more stable
  • Changed: Swiff.Uploader options, swf is now the url to the swf and url the upload url
  • Fixed: Fixed a bug with multiple uploaders on one page, they all work with one injected swf
1.0 pre (2007-05-23)
  • Initial official Release

License

All files are © 2008-2009 by Harald Kirschner and available under the MIT License.

Contact & Discussion

For asking questions, requesting features, filing bugs or contributing other thoughts on this project use the support forum below. Before posting a new question, read through the documentation and the contributed notes for an answer. For problem reports make sure to add enough details like browser, version and a link or the relevant code.

You can contact me for non-support related notes.

Professional Support

I am available for hire if you look for professional and swift help. I can come to your rescue for installation, customization or extending the existing source for your needs.

Share it: Stumble it!Digg This!del.icio.us (No Posts)

discussion by DISQUS No Comments

Please use the support forums for discussing the project, asking questions or posting bug-fixes!

Sort:
No Comments
No Comments

Post your comment

Please use the support forums for discussing the project, asking questions or posting bug-fixes!


Internet Consultant & Contractor

I'm available to combine forces with you and your team to find the most simple, elegant and convenient web solutions . I await your call.

If you just like my work and want to say Thank You, donate via PayPal or Amazon Wish List.

Developer Resources & Tools