JavaScript API

Events

When calling the jQuery .filePicker plugin you use the jQuery .on method to listen for events. All events end with .filepicker.

$('#filepicker').filePicker({
    // options ...
})
.on('done.filepicker', function (e, data) {
    console.log(data.files);
})
.on('fail.filepicker', function () {
    alert('Oops! Something went wrong.');
});

add

Event fired when files are added to be uploaded.

If e.preventDefault() is called the default action of the event will not be triggered.

/**
 * @param {Object} e
 * @param {Object} data
 */
.on('add.filepicker', function (e, data) {
    //
})

progress

Event fired on upload progress.

/**
 * @param {Object} e
 * @param {Object} data
 */
.on('progress.filepicker', function (e, data) {
    console.log(data.progress); // {total:, loaded:, percentage: }
})

done

Event fired on upload done.

/**
 * @param {Object} e
 * @param {Object} data
 */
.on('done.filepicker', function (e, data) {
    console.log(data.files);
})

fail

Event fired on upload fail.

/**
 * @param {Object} e
 * @param {Object} data
 */
.on('done.filepicker', function (e, data) {
    alert(data.errorThrown);
})

always

Event fired after upload done or fail.

/**
 * @param {Object} e
 * @param {Object} data
 */
.on('always.filepicker', function (e, data) {
    //
})

Additional events can be found for each plugin: UI, Drop, Crop and Camera.

The data Object

The data object is used to maintain the upload state. It contains the files to be uploaded and methods to upload or abort, etc.

You can access:

  • data.state A String with the upload state (pending, sending, sent).
  • data.progress An Object with the upload progress: {total:, loaded:, percentage: }.
  • data.send() Starts the upload and returns a jQuery Promise Object or false if already started.
  • data.abort() Aborts the upload.
  • data.files An array of files to be uploaded and after upload the uploaded files.
  • data.originalFiles An array of the original files.

The file Object

Each file from the data.files array has the follwoing properties:

File Properties Before Upload

Name Type Description
name String The file name.
type String File mime type. Example: image/jpeg
extension String The file extension. Example: jpg
size Number The file size in bytes.
sizeFormatted String The file size formated. Example: 1.2 MB
time Number The file timestamp. Example: 1461500968
timeFormatted String The file timestamp formated. Example: 2016-04-24, 3:29 PM
timeISOString() Function Returns the timestamp as a ISO string. Example: 2016-04-24T14:17:34.000Z
imageFile Boolean Whether is a image file type.
context jQuery Object The file jQuery object element (if UI plugin is used).

File Properties After Upload

Name Type Description
name string The file name.
type string File mime type. Example: image/jpeg
extension string The file extension. Example: jpg
url string The file url.
size integer The file size in bytes.
sizeFormatted string The file size formated. Example: 1.2 MB
time Number The file timestamp. Example: 1461500968
timeFormatted String The file timestamp formated. Example: 2016-04-24, 3:29 PM
timeISOString() Function Returns the timestamp as a ISO string. Example: 2016-04-24T14:17:34.000Z
width integer The image width. Only for images.
height integer The image height. Only for images.
versions object The image versions. Only for images.
versions.{version}.name string The image version file name.
versions.{version}.url string The image version file url.
versions.{version}.size integer The image version file size.
versions.{version}.width integer The image version width.
versions.{version}.height integer The image version height.
imageFile boolean Whether is a image file type.
context jQuery Object The file jQuery object element (if UI plugin is used).

When uploading files and uploadMultiple is disabled (default) you can access the a file property with data.files[0].name.

.on('done.filepicker', function (e, data) {
    console.log(data.files[0].name);
});

However if you uploadMultiple is enabled you should use a for to iterate through the data.files array:

.on('done.filepicker', function (e, data) {
    for (var i = 0; i < data.files.length; i++) {
        console.log(data.files[i].name);
    }
});

Handlers

To override the default action handlers, pass them as options:

$('#filepicker').filePicker({
    // options ...
    add: function (e, data) {
        //
    }
})

add

The file add handler.

/** *
 * @param {Object} e
 * @param {Object} data
 */
add: function (e, data) {

progress

The upload progress handler.

/**
 * @param {Object} e
 * @param {Object} data
 */
progress: function (e, data) {},

done

The upload done handler.

/**
 * @param {Object} e
 * @param {Object} data
 */
done: function (e, data) {},

fail

The upload fail handler.

/**
 * @param {Object} e
 * @param {Object} data
 */
fail: function (e, data) {},

always

The upload always handler.

/**
 * @param {Object} e
 * @param {Object} data
 */
always: function (e, data) {},

validate

The file validation handler.

/**
 * @param  {Object} e
 * @param  {Object} file
 * @return {Boolean}
 */
validate: function (e, file) { }

The upload fallback handler. (Old browsers).

uploadfallback

/**
 * @param {Object} e
 * @param {String} message
 */
uploadfallback: function (e, message) { }

Methods

To get the Filepicker instance call .filePicker again:

var FP = $('#filepicker').filePicker();

Now you can access the Filepicker methods:

fetch

Fetch files from the server.

FP.fetch({limit: 10, offset: 0})
    .done((result) => {
        console.log(result);
    });

update

Update a file from the server, used to crop images.

var options = {
    x:180, y:120,
    width:1400, height:950
};

FP.update('file.jpg', options)
    .done((result) => {
        console.log(result);
    });

delete

Delete a file/files from the server.

FP.delete('file.txt')
    .done((result) => {
        console.log(result);
    });

FP.delete(['another.txt', 'one.txt'])
    .done((result) => {
        console.log(result);
    });