You sometimes want the user let transfer some files from the client to the server, for example for attaching them to an electronic mail. The FileUploader control combines the ease of use and configurable appearance of the library controls with the functionality of the <input type="file"> element. The required HTML <form> element, its encoding, and the target window for the submit response are managed under the hood.
FileUploader consists of an editable TextField, containing the name of the currently selected file, and of a Button which opens the standard browser file selection dialog. When the user selects a file from the dialog, the file name will be displayed in the TextField again. The file upload can be triggered either automatically or using a method.
To use the FileUploader, create a control instance, configure at least the upload URL and the name of the upload. The upload shall be triggered directly after the user has selected a file.
To verify the results of the upload, check the following file list. It displays all files in the upload area (server side) of this application and is updated automatically.
As mentioned already there are two ways to trigger the file upload, either automatically
(as we have seen in the previous sample) or explicitly by calling the upload()
method of the FileUploader control. You define the option to use using the uploadOnChange
property. When the property is set to false
, no automatic upload happens. Instead, the application
has to trigger the upload any time later by calling the upload()
method. This can for example be useful
when multiple inputs have to be done before the upload takes place (for example for input of a
server-side file name). The following sample illustrates the explicitly triggered upload.
To check whether the Upload was successful a Return Code has to be generated by the server. This return code with an
optional message has to be put into the HTML Response Document of the iFrame. Within the Response the return code and message
should be put within the body
tags of the document like this for example:
<html><head></head><body>[200]:Upload successful!</body></html>On the client side you have to respond to this response. In our example a Regular Expression is used to parse the response into the return code and the corresponding message:
var m = /^\[(\d\d\d)\]:(.*)$/.exec(sResponse);
Then a Success or Error Message Box can be shown accordingly. However this does not work in cross-domain scenarios.
In case of scenarios where domain relaxing is used security problems may occur because of the document domain. To avoid this the domain has to be handed over to the FielUploader via an additional parameter which has to be put into the response document as document.domain liek this:
<html><head><script>document.domain="domain";</script></head><body>[200]:Upload successful!</body></html>
Also shown within this example is the usage of HTML5 extensions of the FileUploader. Be aware that these functionalities are not supported by Internet Explorer 8 and 9 and you have to declare this as limitation for your application. You can also see how you can react on failed checks for type and size of the files.
The FileUploader provides three possibilities of sending parameters together with the request sent to the server:
additionalData
propertyparameter
aggregationheaderParameter
aggregation (not supported by Internet Explorer 8 and 9)additionalData
property is additional data which will Data will be transmitted as content value where
the name is derived from the name property with suffix -data. The parameter
aggregation can be used to
transfer name/value pairs within the content. In order to transfer header parameters you have to use the
headerParameter
aggregation and set the sendXHR
property to true.
But be aware that setting header parameters and XHR requests are not supported by Internet Explorer 8 and 9 and you
have to declare this as limitation for your application. However if the sendXHR
property is set and the
browser does not support the File API the request will be send as form submit to be backward compatible.
To minimize issues with long file names, the FileUploader control always displays the base name and the extensions without the parent path. In the case the name is still too long, the name is (visually) truncated. The full file name including the path can be provided in the form of a tool tip. The following example also shows some width settings for the FileUploader control. Select a file with a long name and hover over the two FileUploader controls to see the tool tip.