fine-uploader-wrappers

These wrap a Fine Uploader instance as ES6 classes and provide additional features such as the ability to dynamically register multiple event/callback listeners. These classes are requirements in projects such as React Fine Uploader and Vue Fine Uploader, among others.

Docs

Quick Reference

• Installing
• Wrapper Classes

- [Azure](#azure) - upload files directly to Azure storage
- [S3](#s3) - upload files to directly to an Amazon Simple Storage Service (S3) bucket. Your server must sign requests using a private key.
- [Traditional](#traditional) - upload files to a server you created and control.

Installing

If you require support for IE11, you'll need to install an A+/Promise spec compliant polyfill. To install this wrapper classes package, simply npm install fine-uploader-wrappers and see the documentation below for your specific integration instructions (based on your needs).
You'll also need to explicitly install Fine Uploader. See the peerDependencies section of this project's package.json for acceptable version.

Wrapper Classes

Note: You can access the entire qq namespace on any uploader instance. For example, if you are using Fine Uploader S3, and want to access the status object, your code may look something like this:

const uploader = new FineUploaderS3({ ... })
const queuedFileStatus = uploader.qq.status.QUEUED

Azure

This enables you to upload to Azure directly. Your server must provide signature and done endpoints. The Azure uploading workflow is documented on the Azure feature page. Some examples servers can be found in the server-examples repository.

constructor({ options })

When creating a new instance of the Azure endpoint wrapper class, pass in an object that mirrors the format of the Fine Uploader Azure Core options object. This options property is entirely optional.

import FineUploaderAzure from 'fine-uploader-wrappers/azure'

const uploader = new FineUploaderAzure({
    options: {
      signature: {
        endpoint: '/upload/signature',
      },
      uploadSuccess: {
        endpoint: '/upload/done',
      }
    }
})

on(eventName, handlerFunction)

Register a new callback/event handler. The eventName can be formatted with or without the 'on' prefix. If you do use the 'on', prefix, be sure to follow lower-camel-case exactly ('onSubmit', not 'onsubmit'). If a handler has already been registered for this event, yours will be added to the "pipeline" for this event. If a previously registered handler for this event fails for some reason or returns false, you handler will not be called. Your handler function may return a Promise if it is listed as an event type that supports promissory/thenable return values.

uploader.on('complete', (id, name, response) => {
   // handle completed upload
})

off(eventName, handlerFunction)

Unregister a previously registered callback/event handler. Same rules for eventName as the on method apply here. The handlerFunction must be the exact handlerFunction passed to the on method when you initially registered said function.

const completeHandler = (id, name, response) => {
   // handle completed upload
})

uploader.on('complete', completeHandler)

// ...later
uploader.off('complete', completeHandler)

options

The options property you used when constructing a new instance, sans any callbacks.

methods

Use this property to access any core API methods exposed by Fine Uploader Azure.

uploader.methods.getResumableFilesData(myFiles)

S3

Use the traditional endpoint wrapper class if you would like to upload files directly to an Amazon Simple Storage Service (S3 bucket). Your server must be able to sign requests sent by Fine Uploader. If you enable the delete file feature, your server must handle these as well. You can read more about S3 server requests in the documentation. The S3 uploading workflow is documented on the S3 feature page. Some examples servers can be found in the server-examples repository.

constructor({ options })

When creating a new instance of the S3 endpoint wrapper class, pass in an object that mirrors the format of the Fine Uploader S3 Core options object. You may also include a callbacks property to include any initial core callback handlers that you might need. This options property is entirely optional though :laughing:.

import FineUploaderS3 from 'fine-uploader-wrappers/s3'

const uploader = new FineUploaderS3({
    options: {
        request: {
            endpoint: "http://fineuploadertest.s3.amazonaws.com",
            accessKey: "AKIAIXVR6TANOGNBGANQ"
        },
        signature: {
            endpoint: "/vendor/fineuploader/php-s3-server/endpoint.php"
        }
    }
})

on(eventName, handlerFunction)

Register a new callback/event handler. The eventName can be formatted with or without the 'on' prefix. If you do use the 'on', prefix, be sure to follow lower-camel-case exactly ('onSubmit', not 'onsubmit'). If a handler has already been registered for this event, yours will be added to the "pipeline" for this event. If a previously registered handler for this event fails for some reason or returns false, you handler will not be called. Your handler function may return a Promise if it is listed as an event type that supports promissory/thenable return values.

uploader.on('complete', (id, name, response) => {
   // handle completed upload
})

off(eventName, handlerFunction)

Unregister a previously registered callback/event handler. Same rules for eventName as the on method apply here. The handlerFunction must be the exact handlerFunction passed to the on method when you initially registered said function.

const completeHandler = (id, name, response) => {
   // handle completed upload
})

uploader.on('complete', completeHandler)

// ...later
uploader.off('complete', completeHandler)

options

The options property you used when constructing a new instance, sans any callbacks.

methods

Use this property to access any core API methods exposed by Fine Uploader S3.

uploader.methods.addFiles(myFiles)
uploader.methods.deleteFile(3)

Traditional

Use the traditional endpoint wrapper class if you would like to upload files to a server you control. Your server must handle all requests sent by Fine Uploader, such as upload, delete file (optional), and chunking success (optional). You can read more about traditional server requests in the documentation. Some examples servers can be found in the server-examples repository.

constructor({ options })

When creating a new instance of the traditional endpoint wrapper class, pass in an object that mirrors the format of the Fine Uploader Core options object. You may also include a callbacks property to include any initial core callback handlers that you might need. This options property is entirely optional.

import FineUploaderTraditional from 'fine-uploader-wrappers'

const uploader = new FineUploaderTraditional({
   options: {
      request: {
         endpoint: 'my/upload/endpoint'
      },
      callbacks: {
         onComplete: (id, name, response) => {
            // handle completed upload
         }
      }
   }
})

on(eventName, handlerFunction)

Register a new callback/event handler. The eventName can be formatted with or without the 'on' prefix. If you do use the 'on', prefix, be sure to follow lower-camel-case exactly ('onSubmit', not 'onsubmit'). If a handler has already been registered for this event, yours will be added to the "pipeline" for this event. If a previously registered handler for this event fails for some reason or returns false, you handler will not be called. Your handler function may return a Promise iff it is listed as an event type that supports promissory/thenable return values.

uploader.on('complete', (id, name, response) => {
   // handle completed upload
})

off(eventName, handlerFunction)

Unregister a previously registered callback/event handler. Same rules for eventName as the on method apply here. The handlerFunction must be the exact handlerFunction passed to the on method when you initially registered said function.

const completeHandler = (id, name, response) => {
   // handle completed upload
})

uploader.on('complete', completeHandler)

// ...later
uploader.off('complete', completeHandler)

options

The options property you used when constructing a new instance, sans any callbacks.

methods

Use this property to access any core API methods exposed by Fine Uploader.

uploader.methods.addFiles(myFiles)
uploader.methods.deleteFile(3)