Web UI Upload Providers

Upload providers are objects that encapsulate custom upload logics. These can be contributed to Web UI to define how and where blobs will be uploaded to.

Blob upload through Web UI is controlled by the UploaderBehavior, which is part of the Nuxeo UI Elements library, and must be extended by elements that upload files to a Nuxeo instance. To achieve this, a default upload provider is provided, which relies on the DefaultBatchHandler server side. However, custom upload providers can be contributed to fit different batch handlers. For example, it allows blobs to be uploaded directly to an external service.

Upload Provider API

A custom upload provider must be declared as a Javascript function, which will be used as a constructor to create new instance of the provider. The constructor must receive the following parameters:

• connection: an instance of nuxeo-connection
• accept: a string containing a comma-separated list of mime types that are accepted by the provider
• batchAppend: a boolean specifying whether files to be uploaded should be appended to the current batch (if true) or a new one should always be created (if false).

The provider must also expose the following methods:

• upload: accepts an array of files and an uploadCallback, and is responsible for creating a batch on the server and uploading the files
• cancelBatch: cancels the current batch and cleans up after it
• batchExecute: executes an operation on the current batch
• accepts: determines where a given file can be uploaded by the provider or not
• hasProgress: indicates whether the provider can report upload progress or not

The uploadCallback should be called in the following events:

• uploadStarted: the upload has started
• uploadProgress: the upload progress has changed
• uploadCompleted: the upload is completed
• uploadInterrupted: the upload is interrupted
• batchFinished: batch handler was successfully notified that the upload is completed
• batchFailed: there was an error when notifying the batch handler that the upload is completed

Registration and Configuration

A custom upload provider must be registered with a unique name in order to be accessible in Web UI:

Nuxeo.UploaderBehavior.registerProvider('my-provider', MyProvider);

However, this won't make any element extending the UploaderBehavior using it by default. If you want a specific element to use a custom provider, the provider attribute should be set to that provider name. For example, if we want to use a nuxeo-file with a custom upload provider (here named my-provider) instead of the default one, we could do it as follows:

<nuxeo-file provider="my-provider" value="{{value}}"></nuxeo-file>

On the other hand, we can also set it as the default provider to every element extending the UploaderBehavior:

Nuxeo.UploaderBehavior.defaultProvider = 'my-provider';

Examples

For implementation examples of Web UI upload providers, check the default provider and the S3 direct upload provider.