Switch branches/tags
Find file
Fetching contributors…
Cannot retrieve contributors at this time
300 lines (210 sloc) 17.6 KB

Previous Version {#big-important-note}

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 {#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 {#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 {#how-to}

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

Documentation {#docs}

Class: Swiff.Uploader



var uploader = new Swiff.Uploader([options]);


  1. options - (object, optional) See options below. Also inherited are all the options from Swiff.


  • (object|false) - New Swiff.Uploader instance.


  • 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
  • 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.


  • 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.

  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.

  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 {#faq}

How do I access the uploaded files?

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

- PHP: $_FILES['Filedata']
- Perl: $main::cgi->param('Filedata'); ... [example](
- Rails: params[:Filedata] ... [example](
- ASP: [Fancy Upload and Classic ASP](

*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 {#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 {#download}

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


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 {#references}