Javascript drag and drop used by filestack

---

• Filestack Drag And Drop
  • Getting Started
    • UMD module
    • SRI
  • Objects:
    • FilestackDnD
      • Constructor
      • Properties
      • Methods
    • ElementHelper
      • Properties
      • Methods
    • UploadHelper
      • Methods
  • Events
    • How to listen to events
    • How to send events
  • Examples of usage
  • Contributing

Filestack Drag And Drop

With Filestack-Drag-and-Drop you can easily add drag-and-drop file uploading support to your website. You only need 3 lines of code to make any element on your page able to do that. Filestack-drag-and-drop is a frontend to our JavaScript SDK library.

Getting Started

UMD module

To integrate FIlestack-Drag-and-Drop with your web application simply include our UMD module in your code:

<script src="//static.filestackapi.com/filestack-drag-and-drop-js/{MAJOR_VERSION}.x.x/filestack-drag-and-drop.min.js"></script>

Add an element to your page:

<div class="drop-container">Drag and Drop</div>

and initialize Filestack Drag and Drop:

const filestackDnD = new filestackDnD.init('API_KEY', document.querySelector('.drop-container'));

That's it. Now your page element handles the upload by dropping a file on it.

Example initialization with filestack Client:

const filestackClient = filestack.init('API_KEY');
const filestackDnD = new filestackDnD.init(filestackClient, document.querySelector('.drop-container'));

Example initialization with Options (only image, max size: 1024, max files: 2):

const config = {
  accept: ['image/*'], // default empty array - all files
  maxSize: 1024, // default 0 - no limit
  maxFiles: 2, // default 0 - no limit
  failOverMaxFiles: false, 
}

const filestackDnD = new filestackDnD.init('API_KEY', document.querySelector('.drop-container'), config);

Example initialization with sdkConfig:

const sdkConfig = {
  cname: 'cname_test',
  security: {
      policy : 'policy_test',
      signature: 'signature_test'
  }
}

const filestackDnD = new filestackDnD.init('API_KEY', document.querySelector('.drop-container'), null, null, testConfig);

SRI

Subresource Integrity (SRI) is a security feature that enables browsers to verify that files they fetch (for example, from a CDN) are delivered without unexpected manipulation. It works by allowing you to provide a cryptographic hash that a fetched file must match

To obtain sri hashes for filestack-tools library check manifest.json file on CDN:

https://static.filestackapi.com/filestack-drag-and-drop-js/{LIBRARY_VERSION}/manifest.json

<script src="//static.filestackapi.com/filestack-drag-and-drop-js/{LIBRARY_VERSION}/filestack-drag-and-drop.min.js" integrity="{FILE_HASH}" crossorigin="anonymous"></script>

Where {LIBRARY_VERSION} is currently used library version and {FILE_HASH} is one of the hashes from integrity field in manifest.json file

Objects:

FilestackDnD

Constructor

constructor(apikey: string | Client, element?: HTMLElement, options?: OptionsInterface, sdkConfig?: ClientOptions)

Name	Type	Description
apikey	string | Client	Application ApiKey or instance Client from filstackSDK
element (optional)	HTMElement	The HTML element that should listen to events
options (optional)	OptionsInterface	Settings related to uploading
sdkConfig (optional)	Client	Settings for SDK

Properties

Name	Type	Description
elementsHelper	ElementHelper	Manages elements
eventEmitterHelper	EventEmitter	Manages events
uploadsHelper	UploadHelper	Manages uploading
filstackSdk	Client	Client form filstackSDK

Example: Use elementsHelper - set new HTMLElement:

filestackDnD.elementHelper.setElement(document.querySelector('.someElement'))

Use eventEmitterHelper - listen to events:

filestackDnD.eventEmitterHelper.on('dragover', (res) => {console.log(e)})

Use uploadsHelper - set Upload Options:

filestackDnD.uploadsHelper.setUploadOptions()

Use filstackSdk - open picker:

filestackDnD.filstackSdk.picker(options).open();

Methods

Name	Parameters	Description	Return
setElements	elements: HTMLElement | HTMLElement[] | NodeListOf	Adds elements to support Drag and Drop	void
setUploadOptions	uploadOptions: UploadOptions	Adds an option to upload files	void
on	event: string, ...args: any[]	Listening to events. List of available events	void
emit	event: string, listener: Listener	Sending events. List of available events	void

ElementHelper

Properties

Name	Type	Description
elements	HTMLElement[]	Manages elements

Methods

Name	Parameters	Description	Return
setElement	element: HTMLElement	Adding an item. Previous elements are overwritten	void
setElements	elements: HTMLElement[] | NodeListOf	Adding items. The previous ones are overwritten	void
addElement	element: HTMLElement	Adding element to the list	void
addElements	elements: HTMLElement[] | NodeListOf	Adding items to the list	void

UploadHelper

Methods

Name	Parameters	Description	Return
setUploadOptions	uploadOptions: UploadOptions	Set upload Options	void
setStoreUploadOptions	storeUploadOptions: StoreUploadOptions	Set store upload options	void
setSecurity	security: Security	set security config	void

Events

You can interact programmatically with Filestack Drag and Drop

How to listen to events

filestackDnD.on('eventName', (e) => {console.log(e)});

Name	Description	Return
successReadFile	Reading files through browsers	SuccessReadFileInterface
progress	Checking the progress	ProgressInterface
dragover	Event triggered when an object is dragged over an element added to Drag and Drop	{ elementId: string, data: DragEvent }
dragleave	Event triggered when the user moves the cursor outside a Drag and Drop supported item	{ elementId: string, data: DragEvent }
drop	Event triggered when user drops a file over an item	{ elementId: string, data: DragEvent }
uploadFileFinish	Event triggered when uploading a file is successful	{ elementId: string, files: NormalizeFileInterface[], data: res }
error	Event triggered when there are some errors e.g. wrong file format, problems with uploading etc	EventInterface

How to send events

filestackDnD.emit('eventName', { elementId: null, fileId: id });

• elementId: string - This is the identifier of the HTML element. A unique attribute is added: "data-fs-dnd-element-id" To every element added to DragAndDrop.
• fileId: string - Each file has its own unique Id.

If we send an elementId to some event, the event will be called for all files added to this element. If we send only fileId the event will be fired only for the specific file

Name	Description
pause	Stops the upload
resume	Resumes the upload
cancel	Aborts file upload

Examples of usage

Take a look at the examples folder as well. We show various use cases there (example_simple.html):

Multiple drag and drop elements on the page (example_multi_pane.html):

List of uploaded files with progress (example_file_lists.html):

Contributing

We follow the conventional commits specification to ensure consistent commit messages and changelog formatting.