5.15.4

Statistics and Status Updates

Fine Uploader provides API methods and other options to facilitate statistics and status updates on your uploads.

With this, we can register a callback that allows us to be notified when any submitted item changes status. The concept is simple: this will be invoked whenever any submitted file changes state. The ID, old status, and the new status will be included in the callback parameters.

The status values correspond to those found in the qq.status object. For reference, here are valid status values:

  • SUBMITTING - Selected file is in the process of being submitted to the uploader. Validation checks occur during this phase.
  • SUBMITTED - Selected file has been successfully submitted to the uploader. In UI mode, it is also now represented in the DOM.
  • QUEUED - Uploads are in progress, but this one has not yet started due to lack of available connections. It is waiting in line for an available connection before an attempt is made to upload it.
  • UPLOADING - File is currently uploading (in progress).
  • UPLOAD_RETRYING - The state when an upload retry is about to occur, just before the auto retry waiting period starts.
  • UPLOAD_FAILED - The upload has officially failed to upload, after all auto-retry attempts have been exhausted.
  • UPLOAD_SUCCESSFUL - The upload has officially succeeded.
  • CANCELED - The upload has been canceled.
  • REJECTED - The submitted file has failed validation, either via the internal validation checks, or via a validate, validateBatch, or submit event callback.
  • DELETED - The file has been successfully deleted from the server.
  • DELETING - A delete attempt is in progress.
  • DELETE_FAILED - The last delete attempt failed.
  • PAUSED - The file was in progress, but is now paused.

Examples

Simple status query

The API method allows you the retrieve information about all items submitted to the uploader. If you invoke this method without any arguments, information on all items will be returned. For example, suppose we have submitted only two files to the uploader, and both have uploaded successfully. If we wanted to retrieve information about these files, the following code should be executed. Note that I have illustrated the expected return value as well:

var uploads = myUploader.getUploads();

//the uploads return value will look like this:
[
  {
    id: 0,
    name: "some_name",
    size: 12345,
    uuid: "some_uuid",
    status: "upload successful"
  },
  {
    id: 1,
    name: "some_other_name",
    size: 67890,
    uuid: "some_other_uuid",
    status: "upload successful"
  }
]

Now, suppose we delete the second files via Fine Uploader. If we invoke a new-argument getUploads() again, we receive the following in return:

var uploads = myUploader.getUploads();

//the uploads return value will look like this:
[
  {
    id: 0,
    name: "some_name",
    size: 12345,
    uuid: "some_uuid",
    status: "upload successful"
  },
  {
    id: 1,
    name: "some_other_name",
    size: 67890,
    uuid: "some_other_uuid",
    status: "deleted"
  }
]

Filtering results

Note that you can filter by ID(s) OR UUID(s) OR status. You can include multiple ID, UUID, or status values as an array as well. All valid status values are defined in the qq.status object. Also, please note that the size property will only be included if the user agent supports the File API (that is, if qq.supportedFeatures.canDetermineSize evaluates to true).

Suppose we only want to compile a list of all deleted files for this instance, we can do this:

var uploads = myUploader.getUploads({
  status: qq.status.DELETED
});

//the uploads return value will look like this:
[
  {
    id: 1,
    name: "some_other_name",
    size: 67890,
    uuid: "some_other_uuid",
    status: "deleted"
  }
]

Now, suppose we have submitted another file, but we have canceled it. Maybe we only want information about canceled OR deleted items:

var uploads = myUploader.getUploads({
  status: [qq.status.DELETED, qq.status.CANCELED]
});

//the uploads return value will look like this:
[
  {
    id: 1,
    name: "some_other_name",
    size: 67890,
    uuid: "some_other_uuid",
    status: "deleted"
  },
    {
    id: 2,
    name: "some_other_name_2",
    size: 11111,
    uuid: "some_other_uuid2",
    status: "canceled"
  }
]

Note:

getUploads returns an array only when there is a potential for the operation to return more than one file in the result set. This excludes queries for a specific, single ID or UUID. All other queries will return an array.

Determine if all submitted files are "done"

How can I determine if all of my uploads are complete? This is very much a frequently asked question. Luckily, is quite simple to make this determination by contributing an onAllComplete event handler.