Jul 19, 2013

How to customize widget for file uploads

New-era services like Uploadcare allow users to integrate all cloud resources with applications and websites. Although in-built widgets make a great service making it easy to choose and add deliver files on the web, some nice customization will never be redundant.

Here an example of widget customization will be shown. Start with Uploadcare Quick Start page to install the basic version of the uploader.

However, in advanced cases you may want to use your own design or logic. In this case, you want to use Uploadcare JS API to customize the behaviour of our widget.

To use Uploadcare JS API, you have to add this to the <head> of your web page:

<!-- The best place for this one is your <HEAD> tag -->
<script>UPLOADCARE_PUBLIC_KEY = "demopublickey";</script>
<script src="https://ucarecdn.com/widget/0.10/uploadcare/uploadcare-0.10.min.js"></script>

Replace “demopublickey” with your own public key if you’re signed up with Uploadcare. If you’re not, you can use this demo key for now, it works just fine, but files uploaded to this account are being periodically cleaned up.

First thing that happens to a file is it being uploaded. If you’re using our widget, visitors of your website can upload a file by drag-n-dropping it on the widget, or by opening a dialog and choosing a file from their computer or social network accounts, or by copy-pasting its url.

From the JS API perspective, you can upload file from any URL or from an event objet (like a dragndrop event):

var file = uploadcare.fileFrom('url', 'http://example.com/image.png');
var droppedFile = uploadcare.fileFrom('event', e);

To construct a file object from a file, already uploaded to your account, you can use the same method:

var droppedFile = uploadcare.fileFrom('uploaded', '61783708-7090-4d6a-b82b-81f98e40a327');

You can also show a dialog to let the user select a file she wants to upload:

var dialog = widget.openDialog();
dialog.done(function(file) {
    // file was selected
});

 Uploadcare JS API is based on Deferreds. Deferred is an object which can be done, failed or in progress. As you can see, Dialog is a deferred: it’s “done” when user have chosen a file, “failed” if she decided not to, and “in progress” until any of these happens.

Uploadcare File is a deferred, too: it can be already uploaded, the upload may had been failed, or it can be uploading at this moment.

The point of Deferred is management of callbacks. You can add new callbacks to be called after the file, for example, is uploaded:

file.done(function(fileInfo) {
    // Upload successfully completed and file is ready.
}).fail(function(error, fileInfo) {
    // Upload failed or something else went wrong.
}).progress(function(uploadInfo) {
    // State of upload is updated.
    // This callback is invoked at least once with current state,
    // immediately after assignment.
});

You can use a file promise to output the progress of an upload, like this:


file.progress(function(info) {
    $('#message').text(({
        uploading: 'Uploading...',
        uploaded: 'Loading info...',
        ready: 'Done.'
    })[info.state]);
    console.log(info.progress) // percentage of a file uploaded
});

This function will be called many times while the file is uploading, so you can output a progress bar. We have a progress circle in our JS bundle, which can be used just like this:

var circle = uploadcare.Circle('#progress');
circle.listen(file, 'progress');

You can read more about our JS API in the documentation.

Blog comments powered by Disqus

About
Uploadcare handles uploading, storage and processing files for you.