Version

WebUpload Using Client Side Events

The WebUpload control exposes a rich client-side API featuring a number of events. There are seven different client-side events, which are fired either while the user is interacting with the control or during the upload process.

Attach to Client-Side Event in WebUpload

You attach a handler by defining the function name in the ClientEvents tag of the WebUpload. Then, you must create a JavaScript function with the same value to handle the event.

For example consider the fileSelecting event, which is described later in Client Events section of this document.

In ASPX: 
<script type="text/javascript" language="javascript">
 function fileSelecting(e, args) {
 }
</script>
<igjq:WebUpload ID="webUpload1" runat="server">
 <ClientEvents FileSelecting="fileSelecting"/>
</igjq:WebUpload>

Inside the attached handler you can implement any necessary logic. For this you can use the attributes of the event, which is named the same for all the events - e for the event, args for the arguments. Depending on the event, the args arguments contains a different set of properties.

Note: Remember that if you want to cancel an event (cancellable events are fileSelecting and fileUploading) you just need to return false from the function.

Client Events

Table 1: Client events available from the igUpload control

Event Name Description

fileSelecting

The fileSelecting event is fired immediately after the browse button is clicked. When this event fires you have an opportunity to cancel the process of populating the browsing window.

The args attribute is empty when the fileSelecting event is fired. When cancelled (by returning false from the function) the browse dialog is not shown.

fileSelected

The fileSelected event is fired just after a file is selected from the browser pop-up window.

Upon selection, the event arguments already have some basic information about the file. The args object has two properties:

fileID: A consecutive number for every file starting from 0. This useful for multiple upload scenarios, where you can use the ID to identify the different files.

filePath: Name of the selected file

Note
Note:

The cycle of firing fileSelecting and fileSelected events is repeated, when adding additional files.

fileUploading

The fileUploading event is fired during the upload process and is fired while file is uploading. This event is cancelable.

The first time the event is invoked is when the button for uploading the file is pressed. Then depending on the progressUpdateInterval value (which determines the refresh period), the fileUploading event is fired again.

At this point, the event args contains the following information:

fileID: A consecutive number for every file starting from 0. This useful for multiple upload scenarios, where you can use the ID to identify the different files.

filePath: Name of the selected file

fileStatus: Integer representing the status of the file. The value is determined by the server, where an enumeration that maps the integer value with the description of the status. For more information see Table 2.

TotalSize: Returns the file size sum of all selected files to upload. The metric is bytes.

UploadedBytes: Returns current amount of uploaded bytes when the fileUpload event is fired.

You can also cancel this event by returning false value in the event handler method.

fileUploaded

The fileUploaded event is fired when all the files are uploaded to the server. When the event is raised the args parameter contains the three properties fileID, filePath and TotalSize. For details on these items see the fileUploading event.

fileUploadAborted

The fileUploadAbort event is fired if you cancel individual file upload using the cancel button associated with each file. The event args object has the same properties as fileUploading arguments, the only difference is that status is with the value of the canceled file.

cancelAllClicked

The cancelAllClicked event is fired when during the process of uploading when the user clicks the global Cancel button, which is valid for all uploaded files.

onError

The onError event fires when an exception is thrown on the server or client side.

The event args contain the following information:

errorCode: Integer that represents the error code. Table 3 details server side error codes and Table 4 details client error codes.

errorMessage: Detailed error information

errorType: Type of error - the values can be either server-side or client-side.

serverMessage: This is property is able to be set during the server event UploadStarting. If not set it’s an empty string. (You can use it to display custom error messages.)

Note
Note:

Keep in mind that you may want to attach a handler to the onError event to monitor the status of the upload. If an error occurs on the server, the event will fire and the errorCode will expose the underlying problem with the operation. Further, you can also use the localized JavaScript files, which are ig.ui.upload-en.js and ig.ui.upload-jp.js, to find the localized error descriptions. You can also define you own strings for the errors in those files.

onFormDataSubmit

The onFormDataSubmit event fires before submitting the uploading file(and its additional data if any) to the server. It could be used to append additional data fields to the FormData object.

The event args contain the following information:

fileId: Gets unique identifier of the file.

fileInfo: Gets reference to the fileInfo object - contains information for the fileName, fileSize, serverMessage, etc.

xhr: Gets reference to the original XMLHttpRequest object(if the browser supports HTML 5 file API - if not it is undefined).

formData: Gets reference to FormData object(if the browser supports HTML5 file API) or reference to jQuery representation of < form >

onXHRLoad

The onXHRLoad event is fired when the onload(of XmlHttpRequest) is fired. This event will be fired only if the browser supports HTML5 API.

The following tables map the message codes returned from the server with their meanings.

Table 2: Enumeration of type UploadStatus

Value Description

0

File is not started

1

File Uploading is started

2

File Upload is finished

3

File not found - this status is used when it is not found such key in the dictionary

4

Cancel file uploading by client command

5

Size of the file exceeded

6

Error while file is uploading

7

File upload is cancelled from server-side event handler

8

File uploading is cancelled by dropping client connection

9

Status of file when the whole content is uploaded but the file is with temporary filename

Table 3: Enumeration of type FileError (for server side error)

Value Description

-1

No error

0

File error occurs when getting file name from the request

1

MIME type validation failed

2

File size exceeded

3

Temporary folder where file should be uploaded could not be found

4

Error while parsing request header

5

File does not exist with the specified key in the request

6

Error occurs when file saving fails

7

Error occurs when trying to write file content

8

Error occurred when trying to write file content for the first time

9

Error occurred when trying to delete file

10

Error set when file upload is cancelled on start uploading in event handler

Table 4: Enumeration of type FileError (for client side error codes)

Value Description

1

Max allowed uploading files exceeded

2

Client side extenstion validation

3

Error thrown when trying to start upload file with not existing id

4

Ajax error when trying to get file status

5

Ajax error when trying to call cancel command in httpHandler

6

Error occurs when trying to remove file upload with not existing id

7

Ajax error when trying to get file size

8

Error thrown when trying to check if the file could be canceled and maxSimultaneousFilesUploads

Is less or equal to 0

Related Links

WebUpload Client-side Events Samples

WebUpload Overview