CDN Note

FileUploader does work with the Google and AOL CDNs,but because of cross domain issues,you need to run the SWF locally,and point to its location with dojoConfig.uploaderPath.

Dojo Version 1.2.x

The FileUploader version 1.1 and 1.2 is no longer supported. FileUploader 1.2 programmatically called the Flash browse() method which Adobe soon after removed for security reasons.

Dojo Version 1.3

This version is supported but has limitations. It floats the SWF over the styled button,so the CSS is tricky and not always 100% accurate. And this will not work in many cases where the button is in scrolling content,specifically Windows and Linux Firefox.

Dojo Version 1.3.2

This version is a major upgrade from 1.3,makes CSS placement easier and fixes the scrolling bug. However there is an IE8 bug that was not caught at the time of release. This bug can be patched using the instructions found in the Trac ticket:

http://bugs.dojotoolkit.org/ticket/9615

Another bug found is uploading multiple files more than once causes onComplete to fire on every file. It should only fire after all files have uploaded. The fix for this is to use the SWF from the trunk (1.4) in the 1.3.2 release.

http://bugs.dojotoolkit.org/ticket/9646

Dojo Version 1.4.0

This version has some serIoUs upgrades,including a more robust upload system that has been tested to upload 500 files and 500 megs. This version also fixes several bugs including the ability to display the uploader in a Dialog.

Dojo Version 1.5.0

This version adds the ability to use the uploader in a TabContainer. However,see the next section.

Dojo Version 1.6.0

dojox.form.FileUploader is now deprecated. Use dojox.form.Uploader instead.

Setup

The button styles are now recreated in Flash,so there is no longer an invisible Flash movie with wmode=transparent. This way the Flash button is actually placed inline with the DOM,not floating above it and constantly resetting its position. The “Windows Firefox clickable bug” should be fixed (and hopefully some Linux problems).

The HTML button is created in a new way and it is now inline as is the Flash button. Styling is much easier and more versatile.

The process is to create a typical HTML button,with either a button,input,div,or span tag. Button tags work the best. Style the button how you would like it to look in CSS. Then create another class that will append to the class chain to style the button in its hover state. Follow the same procedure for active state (press) and disabled state. Assign the normal class to your button and make the widget either programmatically or with markup.

A basic example follows:

.uploadBtn{
    border:1px solid #333333;
    background:url(buttonEnabled.png) #d0d0d0 repeat-x scroll 0px top;
    font-size:14px;
    width:201px;
    height:30px;
    vertical-align:middle; /* emulates a <button> if node is not */
    text-align:center;
}
.uploadHover{
    background-image:url(buttonHover.png);
    cursor:pointer;
    font-weight:bold;
}

.uploadPress{
    background-image:url(buttonActive.png);
}
.uploadDisabled{
    background-image:none;
    background-color:#666;
    color:#999;
    border:1px solid #999;
}

<div id="btn" class="uploadBtn">Select Files</div>

var uploader = new dojox.form.FileUploader({
    hoverClass:@H_503_502@"uploadHover",
    activeClass:@H_503_502@"uploadBtn",
    pressClass:@H_503_502@"uploadPress",
    disabledClass:@H_503_502@"uploadDisable",
    uploadUrl:pathToUploadServerScript
}, @H_503_502@"btn");

Or,using the same CSS,create it as markup:

<div class="uploadBtn" data-dojo-type="dojox.form.FileUploader" data-dojo-props="hoverClass:'uploadHover',pressClass:'uploadPress',
     activeClass:'uploadBtn',disabledClass:'uploadDisable',uploadUrl:'../serverpage.PHP'">Select Files</div>

Dependencies

FileUploader no longer uses FileInput.css. It now uses FileUploader.css. See requires for JavaScript dependencies.

New Features

• Disabled: Can be toggled with widget.set(“disabled”,true|false)
• Submit: A convenience method has been added for if the uploader is in a form. Instead of submitting the form,call uploader.submit(theForm),and the Uploader will handle all of the form values and post the data.
• Selected List: If passing the ID of a container,the Uploaders will populate it with the selected files.
• Deleting Files: You can now delete pending files.
• Progress Built in: showProgress:true will change the button to a progress bar on upload.
• Progress Attach: Passing progressWidgetId will tell the Uploader of a progress widget. If the Progress widget is initially hidden,it will change to visible and then restored after upload.
• A11Y: The Flash button can be accessed with the TAB key. (The HTML cannot due to browser limitations)
• Deferred Uploading: (Flash only) throttles the upload to one file at a time

Changed in 1.4: deferredUploading is now mandatory to prevent errors in Firefox and Safari. It accepts a number and the idea is you can upload more than one file in parallel,though my tests have shown it always does one at a time anyway. This change makes the upload a little slower,but now it is much more robust and can handle uploads of 500 files or more without crashing the browser.

There are two new tests added to DojoX: test_FileUploaderCSS.html and test_FileUploaderForm.html. The form test will show how to implement most of the new features. The CSS test will show different methods of styling the Uploader.

http://mwilcox.dojotoolkit.org/dtk/dojox/form/tests/test_FileUploaderForm.html

http://mwilcox.dojotoolkit.org/dtk/dojox/form/tests/test_FileUploaderCSS.html

Continue with the 1.3 instructions for other information that still applies to implementing the FileUploader.

Version 1.3

Version 1.3 does NOT create a button - it transforms an existing button into an uploader. This can be used for toolbar buttons for example. Because of this,it only works programmatically,it does not work in markup. Use the other other DojoX FileInput files for markup solutions.

FileUploader will detect if the correct version of Flash Player is available,and if so,a transparent SWF is laid over the top of the original (referred to as the ‘fake’) button. If not available,a traditional fileInput button with opacity set to zero is laid over the fake button.

A basic example follows:

var uploader = new dojox.form.FileUploader({
    button:dijit.byId(@H_503_502@"myFakeButton"),
    uploadUrl:uploadUrl,
});

The example has doesn’t show selectMultipleFiles,but it defaults to true. Setting it to false restricts the user to one file selection. Multiple files are also supported in the HTML version,although only one file can be selected at a time. But after the files are selected,they will all be uploaded at once.

The uploadUrl property is the location of the server side script. Note that this URL needs to be relative to the SWF,not to the HTML page,nor to dojo.js. It’s recommended that an absolute URL is used if possible. FlashUpload will try to “normalize” relative URLs and point them to the SWF.

Use dojo.connect to connect to the onChange,onProgress and onComplete methods:

dojo.connect(uploader, @H_503_502@"onChange", function(dataArray){
    dojo.forEach(dataArray, function(data){
        dojo.byId(@H_503_502@"myTextarea").value += data.name+@H_503_502@" "+Math.ceil(data.size*.001)+@H_503_502@"kb \n";
    });
});
dojo.connect(uploader, @H_503_502@"onProgress", function(data){
        dojo.byId(@H_503_502@"myTextarea").value += @H_503_502@"onProgress: ("+data.percent+@H_503_502@"%) "+data.name+@H_503_502@" \n";
    });
});
dojo.connect(uploader, @H_503_502@"onComplete", function(d){
        dojo.byId(@H_503_502@"myTextarea").value += @H_503_502@"onComplete: "+d.file+@H_503_502@" \n";
    });
});

Use upload to initiate the upload after files have been selected. Or set uploadOnChange to true to initiate upload automatically after the selection.

Note that the “dataArray” param above is always an array,even if selectMultipleFiles is set to false.

Updated: Be careful not to construct the connect so that it sends a mouse event to the upload method (as this example used to do). The upload method expects no arguments or one argument to use as postData. The mouse event will be treated as postData and throw an error. This is fixed in the trunk but exists in 1.32.

dojo.connect(dijit.byId(@H_503_502@"myUploadButton"), @H_503_502@"onClick", function(){
    uploader.upload();
});

Advanced Parameters

The FileUploader has many advanced properties to handle most situations.

fileMask: An array,or an array of arrays. Restrict file selection to certain file types Empty array defaults to “All Files”. NOTE: MacType is not supported,as it does not work very well. fileMask will work on a Mac,but differently than Windows.

var fileMask = [@H_503_502@"Images", @H_503_502@"*.jpg;*.jpeg;*.gif;*.png"]
// or
var fileMask = [
    [@H_503_502@"Jpeg File",  @H_503_502@"*.jpg;*.jpeg"],
    [@H_503_502@"GIF File",   @H_503_502@"*.gif"],
    [@H_503_502@"PNG File",   @H_503_502@"*.png"],
    [@H_503_502@"All Images", @H_503_502@"*.jpg;*.jpeg;*.gif;*.png"],
];
var uploader = new dojox.form.FileUploader({
    button:dijit.byId(@H_503_502@"myFakeButton"),
    fileMask:fileMask
});

force: You can use either HTML (force=”html”) or Flash only,with this parameter. If force=”flash” and the user does not have Flash installed,they will be prompted to install the plugin. “flash” forces Flash Uploader. Defaults to an empty string (force=””) which checks for the availability of the proper Flash player (Flash 9 or higher).

postData: The data that will be sent via POST to the server along with the uploaded files. This data object can bet set on instantiation,and the data will be sent to the server with each file on every upload. You can also pass postData in the upload method as an object argument which can be different with each upload.

Note: as of 1.4.0 there is a bug: http://bugs.dojotoolkit.org/ticket/10559 where postData is not being sent for flash based uploaders where uploadOnChange is also true. This is fixed in 1.5.

Returned postData: Post data is regurgitated to the uploader in the tests. Your case may be different. The SWF returns postdata in an additionalParams object,and it is in this object in which the postdata can be found in the onComplete object. The reason for this was originally to get around AS3 issues,but it turns out to be a good system,as it prevents post data variables from overwriting standard variables such as ‘name’ or ‘file’.

htmlFieldName: The name of the field of the fileInput that the server is expecting. See “Server Side Code” below.

flashFieldName: The name of the field of the flash uploaded files that the server is expecting. See “Server Side Code” below.

Dependencies

dojox.html.styles to create dynamic CSS for an IE workaround.dojo.io.iframe for the HTML POST upload.dojox.embed.Flash for embedding the SWF in the page.dojox/form/resources/FileInput.css for some fileInput styling.

Debugging

Because of the complex nature of the FileUploader code (or more accurately,the hack!). It’s often necessary to do some debugging to test if something is working properly. The following parameters assist with this:

isDebug: Unlike most Dojo code,the logging has been left in the FileUploader,but is disabled by default. isDebug=true will turn on the log messages for inspection. This also passes to the SWF which will output messages of what’s happening in there.

devMode: Changing this parameter to true will set the opacity of the HTML upload button to 100% and remove transparency from the Flash upload button. This helps to determine of the button is being positioned correctly.

Server Side Code PHP

FlashUploader comes with a working PHP file,dojox/form/resources/UploadFile.PHP,to use as a reference for how your server side code should work. UploadFile.PHP has two dependencies,dojo/tests/resources/JSON.PHP,which is used for converting the return data to a JSO string,and dojox/form/resources/cLog.PHP which is used to log message to a text file,placed relative to the PHP file.

UploadFile.PHP is expecting one of three things:

1. A file or files from Flash
2. A file from HTML
3. Multiple files from HTML

The PHP file is inspecting the header and looking for the parameters set in FileUploader: htmlFieldName or flashFieldName. Whatever you set these parameters to,they must match on the server. The current code uses "flashUploadFiles" as the default Flash field name. (The default field name in Flash is "Filedata",which is over written to show that you can do custom field names). Therefore the server must be made aware of this parameter,as it is set on line 69: $fieldName = "flashUploadFiles";

The field name for the HTML uploader works much the same way. The only difference is if you do multi-file upload with HTML,this essentially continues to add fileInputs to the form,and in doing so,appends numbers to the fileInput field names,starting with '0'. That's why one file fieldname will look like "myFieldName" but two files will look like [ "myFieldName0","myFieldName1" ] to the server side code.

Server Side Return Data

How the data is returned from the server is not difficult,but it is very important. If not done correctly,it can be the cause of reported errors that the "onComplete" is not firing in FileUploader.

NOTE The Flash uploader and the HTML uploader need differently formatted return data. You will need to inspect the post data to determine which type to return.

If flashFieldName is found in the post data and Flash is being used on the client side,all that is needed for return data is a key-value string,and it can simply be returned,as at the end of a function. You may also want to insert exit or whatever necessary to cease execution of the remainder of the code. Example:

$data .='file='.$file.',name='.$name.',width='.$width.',height='.$height.',type='.$type;
echo($data);
exit;

For non-PHP devs this translates to:

$name = name of the file,such as "PIC01.jpg"
$file = name of the file and the path,such as "uploaded/PIC01.jpg"
$width,$height = the dimensions (if you are working with images)
$type = the extension of the file - JPG,GIF,PNG,etc.

The return to Flash should look like:

"file=uploaded/PIC01.jpg,name=PIC01.jpg,width=320,height=240,type=jpg"

This string should be returned,or printed,or echoed.

New in 1.4,you can add an error key if one file was in error; say if it was not of the correct type. This error code or message will be returned in the onComplete dataArray. It's important to note that as far as the FileUploader is concerned,everything was a success. It's up to your custom code to test for this error.

The return string with an error might look like:

"file=uploaded/PIC01.jpg,type=jpg,error=Not recognized file type"

You can also send back arbitrary parameters from your server-side script using this comma-delimitted format. For example,adding variables foo and abc:

"file=uploaded/PIC01.jpg,foo=bar,abc=123"

Then you can access these variables in the client-side functions using dataArray[i].additionalParams.foo and dataArray[i].additionalParams.abc.

Note: there is an open ticket http://bugs.dojotoolkit.org/ticket/10576 - when the uploader is set/forced to HTML mode,additionalParams is not created on the client side. In the situation above dataArray[i].foo would exist though.

If htmlFieldName is used,the code on the client side gets pretty tricky,as an iframe is necessary for the file-post,and reading back from that iframe presents problems. In order to read the iframe return data accurately cross browser,the code needs to be wrapped in a <textarea>. You can see the code for this on the very last line of UploadFiles.PHP. Note that the textarea needs to be outside of the PHP. Example:

<?PHP
    ....code....
?>
<textarea><?PHP print $json->encode($dataObject); ?></textarea>

For non-PHP devs,this translates into a JSON string,wrapped in a textarea,returned as HTML. I know it's screwy,but that's how it works.

If you are having problems getting onComplete to fire,look at this code first. Often the problem is the server side code is not catching the flash field name for whatever reason (perhaps the client and server names don't match) and the code is falling to the end of the page and returning a textarea to Flash. Recently Code has been added in the SWF that checks for this,so if that is the problem,you should be notified with a console message.

HTTPS Issues

Attempting to upload to an HTTPS server can be very difficult in Firefox and Safari due to the fact that they do not share the same session as the browser page. IE has much fewer issues. Potential workarounds (mostly unverified as I do not have an HTTPS server to test with):

• Here is the official Adobe bug report on the issue: https://bugs.adobe.com/jira/browse/FP-226
• Firefox does not like self signed security certificates. It has been said that an official signed cert will work.
• It was brought to my attention that an .htaccess files on the server will work with the following content:

<IfModule mod_security.c>
  SecFilterEngine Off
  SecFilterScanPOST Off
</IfModule>

HOWEVER,this site says that opens you up to sql injection attacks. He offers other solutions:http://pumastudios.com/2009/05/file-uploads-and-mod_security-vs-wordpress-wp-adminadmin-ajaxphp

The original poster responds:

This is not only a https issue. It's also on simple http connections. Ist a bug of adobe flash player in conjunction with the web application firewall (modsecurity). If i understand that correctly the flash player sends one "\n\r" instead but the http protocol requires "\n\r\n\r". For modsecutiry this is a rule break so it delivers 403 rejected.

And yes if you disable modsecurity sql injections can be done on all post vars that are later processed by the database an not escaped within the application. So another safer way - until adobe fixed this problem and all flash players are updated - is the following but may not work on all servers:

<IfModule mod_security.c>
 SetEnvIfNoCase Content-Type "^multipart/form-data;" "MODSEC_NOPOSTBUFFERING=Do not buffer file uploads"
</IfModule>

(Thanks to minobun for all the great info on this thorny issue)

The other,less desirable solutions,are:

• Have an HTTP server to handle the uploads and use a crossdomain.xml file to handle the different protocol.
• You may need to resort to force the HTML uploader.

More references to this issue:

• http://bugs.dojotoolkit.org/ticket/8911
• http://bugs.dojotoolkit.org/ticket/10306
• http://wiki.modxcms.com/index.php/What_is_mod_security_and_how_does_it_affect_me
• http://www.modsecurity.org/documentation/modsecurity-apache/1.9.3/html-multipage/06-special_features.html