Telerik Extensions for ASP.NET MVC

This help topic discusses the client-side API and events exposed by Telerik Upload for ASP.NET MVC.

Prerequisites

Important

All Telerik UI components need a ScriptRegistrar component in order to output their JavaScript objects and register their JavaScript files. The ScriptRegistrar component should be defined *after* all other UI components in the page. If you create the components on the client-side and do not use the MVC extensions, you need to manually register all requried JavaScript files. For further information check this help topic (Step 4 - Register Scripts)

How to get Upload client object

The Upload client object is preserved in the data store for the Upload element.

Here is a code snippet showing how to retrieve the client object of the Upload.

CopyView
<%= Html.Telerik().Upload()
        .Name("attachments")
%>
CopyJavaScript
<script type="text/javascript">
    function getUpload(){
        // #attachments is a jQuery selector based on the "id" attribute of the Upload.
        // The id is set using Name()
        var upload = $("#attachments").data("tUpload");
        return upload;
    }
</script>

Client events

Telerik Upload for ASP.NET MVC exposes the following client-side events

  • OnLoad - raised when the Upload is initialized.
  • OnSelect - raised when one or more files are selected (cancelable).
  • OnUpload - raised when one or more files are about to be uploaded (cancellable).
  • OnSuccess - raised when an upload / remove operation has been completed successfully.
  • OnError - raised when an upload / remove operation has failed (cancellable).
  • OnComplete - raised when all active uploads have completed either successfully or with errors.
  • OnCancel - raised when all active uploads have completed either successfully or with errors.
  • OnRemove - raised when an uploaded file is about to be removed (cancellable).

Files list

All events with the exception of OnComplete and OnLoad receive a "files" argument. This is an array with objects that have the following fields:

  • name
  • extension - the file extension inlcuding the leading dot - ".jpg", ".png", etc.
  • size - the file size in bytes (null if not available)

XMLHttpRequest

The OnSuccess and OnError events receive a "XMLHttpRequest". This is either the original XHR used for the operation or a stub containing:

  • responseText
  • status
  • statusText

Verify that this is an actual XHR before accessing any other fields.

OnLoad

The OnLoad event is raised when the Upload is initialized. Here is a short example showing how to handle that event:
CopySubscribing to the OnLoad event
<%= Html.Telerik().Upload()
        .Name("attachments")
        .ClientEvents(events => events
            .OnLoad("onLoad")
        )
%>
CopyHandling the OnLoad event
<script type="text/javascript">
    function onLoad(e) {
        // The upload is now ready to accept user input
    }
</script>

OnSelect (cancellable)

The OnSelect event is raised when one or more files are selected. Cancelling the event will prevent the selection.

Event arguments:

  • files - an array of the selected files.

Here is a short example showing how to handle that event:
CopySubscribing to the OnSelect event
<%= Html.Telerik().Upload()
        .Name("attachments")
        .ClientEvents(events => events
            .OnSelect("onSelect")
        )
%>
CopyHandling the OnSelect event
<script type="text/javascript">
    function onSelect(e) {
        // Array with information about the uploaded files
        var files = e.files;

        if (files.length > 5) {
            alert("Too many files selected!");
            e.preventDefault();
        }
    }
</script>

OnUpload (cancellable)

The OnUpload event is raised when one or more files are about to be uploaded. Cancelling the event will prevent the upload.

Event arguments:

  • files - a list of the files that will be uploaded
  • data - undefined by default, but can be set to a custom object to pass information to the Save action. See Sending and receiving metadata.

Here is a short example showing how to handle that event:
CopySubscribing to the OnUpload event
<%= Html.Telerik().Upload()
        .Name("attachments")
            .Async(async => async
                .Save("Save", "Home")
                .Remove("Remove", "Home")
            )
            .ClientEvents(events => events
            .OnUpload("onUpload")
        )
%>
CopyHandling the OnUpload event
<script type="text/javascript">
    function onUpload(e) {
        // Array with information about the uploaded files
        var files = e.files;

        // Check the extension of each file and abort the upload if it is not .jpg
        $.each(files, function() {
            if (this.extension != ".jpg") {
                alert("Only .jpg files can be uploaded")
                e.preventDefault();
                return false;
            }
        });
    }
</script>
Important
The OnUpload event fires only when the upload is configured for asynchronous upload.

OnSuccess

The OnSuccess event is raised when an upload / remove operation has been completed successfully.

Event arguments:

Here is a short example showing how to handle that event:
CopySubscribing to the OnSuccess event
<%= Html.Telerik().Upload()
        .Name("attachments")
        .Async(async => async
            .Save("Save", "Home")
            .Remove("Remove", "Home")
        )
        .ClientEvents(events => events
            .OnSuccess("onSuccess")
        )
%>
CopyHandling the OnSuccess event
<script type="text/javascript">
    function onSuccess(e) {
        // Array with information about the uploaded files
        var files = e.files;

        if (e.operation == "upload") {
            alert("Successfully uploaded " + files.length + " files");
        }
    }
</script>
Important
The OnSuccess event fires only when the upload is configured for asynchronous upload.

OnError (cancellable)

The OnError event is raised when an upload / remove operation has failed.

Event arguments:

Here is a short example showing how to handle that event:
CopySubscribing to the OnError event
<%= Html.Telerik().Upload()
        .Name("attachments")
        .Async(async => async
            .Save("Save", "Home")
            .Remove("Remove", "Home")
        )
        .ClientEvents(events => events
            .OnError("onError")
        )
%>
CopyHandling the OnError event
<script type="text/javascript">
    function onError(e) {
        // Array with information about the uploaded files
        var files = e.files;

        if (e.operation == "upload") {
            alert("Failed to uploaded " + files.length + " files");
        }

        // Suppress the default error message
        e.preventDefault();
    }
</script>
Important
The OnError event fires only when the upload is configured for asynchronous upload.

OnComplete

The OnComplete event is raised when all active uploads have completed either successfully or with errors. Here is a short example showing how to handle that event:
CopySubscribing to the OnComplete event
<%= Html.Telerik().Upload()
        .Name("attachments")
        .Async(async => async
            .Save("Save", "Home")
            .Remove("Remove", "Home")
        )
        .ClientEvents(events => events
            .OnComplete("onComplete")
        )
%>
CopyHandling the OnComplete event
<script type="text/javascript">
    function onComplete(e) {
        // The upload is now idle
    }
</script>
Important
The OnComplete event fires only when the upload is configured for asynchronous upload.

OnCancel

The OnCancel event is raised when the upload has been cancelled while in progress.

Event arguments:

  • files - a list of the files

Here is a short example showing how to handle that event:
CopySubscribing to the OnCancel event
<%= Html.Telerik().Upload()
        .Name("attachments")
        .Async(async => async
            .Save("Save", "Home")
            .Remove("Remove", "Home")
        )
        .ClientEvents(events => events
            .OnCancel("onCancel")
        )
%>
CopyHandling the OnCancel event
<script type="text/javascript">
    function onCancel(e) {
        // Array with information about the uploaded files
        var files = e.files;

        // Process the Cancel event
    }
</script>
Important
The OnCancel event fires only when the upload is configured for asynchronous upload.

OnRemove (cancellable)

The OnRemove event is raised when an uploaded file is about to be removed. Cancelling the event will prevent the remove.

Event arguments:

  • files - a list of the files that will be removed
  • data - undefined by default, but can be set to a custom object to pass information to the Remove action. See Sending and receiving metadata.

Here is a short example showing how to handle that event:
CopySubscribing to the OnRemove event
<%= Html.Telerik().Upload()
        .Name("attachments")
        .ClientEvents(events => events
            .OnRemove("onRemove")
        )
%>
CopyHandling the OnRemove event
<script type="text/javascript">
    function onRemove(e) {
        // Array with information about the uploaded files
        var files = e.files;

        // Process the Remove event
    }
</script>

Client Methods

Telerik Upload for ASP.NET MVC exposes the following client-side methods:

enable

The enable method enables file selection.
CopyJavaScript
<script type="text/javascript">
    var upload = $('#attachments').data('tUpload');
    upload.enable();
</script>

disable

The disable method disables file selection.
CopyJavaScript
<script type="text/javascript">
    var upload = $('#attachments').data('tUpload');
    upload.disable();
</script>

See Also