jQuery File Uploader JavaScript API: File Groups

We’ve built the next version of the File Uploader.

A group is an ordered collection of file instances. Groups are immutable: once created, they can not be changed. However, you do not have to create a new group every time you delete a file: groups can hold null values.

Create a new group instance

You can create a new group from an array of files and/or other groups.

1 var fileGroup = uploadcare.FileGroup([file1, fileGroup1, file2]);

After a group instance is created, it can be pushed to Uploadcare by calling the promise method.

Get group info

You can subscribe to group upload events to let your app know when all files are uploaded, and a new group is created.

1 var groupPromise = fileGroup.promise();
2 groupPromise.done(function(fileGroupInfo) {
3   // Upload successfully completed and all files in the group are ready.
4 });
5 groupPromise.fail(function(errorType, fileGroupInfo, error) {
6   // Upload failed, or something else went wrong.
7 
8   // `errorType: string` - Indicates the reason or location of the error, e.g. `info`, `baddata` etc.
9   // `fileGroupInfo: GroupFileInfo` - Group file info object if known. Could be undefined.
10   // `error: XMLHttpRequest | { message: string; code: string }` - The error response from the server or XMLHttpRequest instance that threw the error. Could be undefined.
11 
12   // See the list of all the possible error codes and it's messages:
13   // https://uploadcare.com/docs/api/upload/errors/
14 
15   // `error` will be the instance of XMLHttpRequest in case when it's network error
16   // here is example of how to check it
17   const isNetworkError = error && 'readyState' in error
18 });

There is also a way to check out you group upload progress. Make use of the progress function:

1 groupPromise.progress(function(uploadInfo) {
2   // State of upload is updated.
3   // This callback is invoked at least once with current state,
4   // immediately after assignment.
5 });

Get files in group as array

Here is how you get files stored in a group as array:

1 var arrayOfFiles = fileGroup.files();

Get file info on a first-ready-first-served basis:

1 $.each(arrayOfFiles, function(i, file) {
2   // Wait for file uploading.
3   file.done(function(fileInfo) {
4     // i is file positon in group.
5     console.log(i, fileInfo);
6   });
7 });

Get file info in line with their positions in a group:

1 $.when.apply(null, arrayOfFiles).done(function() {
2   // Info for each file will be passed as an argument.
3   var fileInfos = arguments;
4   $.each(fileInfos, function(i, fileInfo) {
5     // i is file position in the group.
6     console.log(i, fileInfo);
7   });
8 });

Get file groups from CDN

Our JavaScript API provides a method to load a file group from CDN via either its identifier or CDN URL.

1 uploadcare.loadFileGroup('cdf2fe62-3d43-47d4-9288-c3951561f5c7~2')
2   .done(function(fileGroup) {
3     // Group creation completed successfully.
4   })
5   .fail(function() {
6     // Something went wrong.
7   });

Object overview, `fileGroupInfo`

This is how the structure of fileGroupInfo looks like,

Property	Type	Value
uuid	string	File group identifier
name	string	Localized group size string, e.g. “5 files”
size	number	Total file size in bytes
isStored	boolean	`true` if all files in a group are stored, `false` otherwise
isImage	boolean	`true` if all files in a group are images, `false` otherwise
cdnUrl	string	File group CDN URL

1	var groupPromise = fileGroup.promise();
2	groupPromise.done(function(fileGroupInfo) {
3	// Upload successfully completed and all files in the group are ready.
4	});
5	groupPromise.fail(function(errorType, fileGroupInfo, error) {
6	// Upload failed, or something else went wrong.
7
8	// `errorType: string` - Indicates the reason or location of the error, e.g. `info`, `baddata` etc.
9	// `fileGroupInfo: GroupFileInfo` - Group file info object if known. Could be undefined.
10	// `error: XMLHttpRequest \| { message: string; code: string }` - The error response from the server or XMLHttpRequest instance that threw the error. Could be undefined.
11
12	// See the list of all the possible error codes and it's messages:
13	// https://uploadcare.com/docs/api/upload/errors/
14
15	// `error` will be the instance of XMLHttpRequest in case when it's network error
16	// here is example of how to check it
17	const isNetworkError = error && 'readyState' in error
18	});

1	groupPromise.progress(function(uploadInfo) {
2	// State of upload is updated.
3	// This callback is invoked at least once with current state,
4	// immediately after assignment.
5	});

1	$.each(arrayOfFiles, function(i, file) {
2	// Wait for file uploading.
3	file.done(function(fileInfo) {
4	// i is file positon in group.
5	console.log(i, fileInfo);
6	});
7	});

1	$.when.apply(null, arrayOfFiles).done(function() {
2	// Info for each file will be passed as an argument.
3	var fileInfos = arguments;
4	$.each(fileInfos, function(i, fileInfo) {
5	// i is file position in the group.
6	console.log(i, fileInfo);
7	});
8	});

1	uploadcare.loadFileGroup('cdf2fe62-3d43-47d4-9288-c3951561f5c7~2')
2	.done(function(fileGroup) {
3	// Group creation completed successfully.
4	})
5	.fail(function() {
6	// Something went wrong.
7	});