Upload

A jQuery plugin for simple drag and drop uploads.

Demo

Demos are largely unstyled to give developers a better idea of how the plugin can drop into a new or existing project.

<div class="upload"></div>

$(".upload").upload({
  action: "//example.com/handle-upload.php"
});

View All Demos

Using Upload

Main

upload.js
upload.css

Dependencies

jQuery
core.js

Basic

Upload will create a simple 'drop zone' for file uploads:

$(".target").upload({
  action: "upload.php"
});

<div class="target"></div>

Note: Older browsers do not support the File API. Developers will need to provide a proper fallback. Support can be checked in the Formstone.support object:

if (Formstone.support.file) {
  ...
}

Form Data

Form Data can be modified before the request is made. The request can also be aborted based on file attributes:

$(".target").upload({
  beforeSend: onBeforeSend
});

function onBeforeSend(formData, file) {
  // Cancel request
  if (file.name.indexOf(".jpg") < 0) {
    return false;
  }

  // Modify and return form data
  formdata.append("input_name", "input_value");

  return formData;
}

Abort

Active uploads can be aborted one at a time by passing the file's index, or abort the entire queue by excluding the second parameter:

// Abort single file
$(".target").upload("abort", file.index);

// Abort entire queue
$(".target").upload("abort");

Uploads

Upload does not store or manipulate uploaded files on the server, it simply facilitates the asynchronous upload process from the front end.

Options

Set instance options by passing a valid object at initialization, or to the public defaults method. Custom options for a specific instance can also be set by attaching a data-upload-options attribute to the target elment. This attribute should contain the properly formatted JSON object representing the custom options.

Name	Type	Default	Description
`accept`	`string`		Input accept attribute
`action`	`string`		Where to submit uploads
`autoUpload`	`boolean`	`false`	Beging upload when files are dropped
`beforeSend`	`function`		Run before request sent, must return modified formdata or `false` to cancel
`chunked`	`boolean`	`false`	Use chunked uploading, if supported
`chunkSize`	`int`	`100`	Size to chunk, in kB
`customClass`	`string`	`''`	Class applied to instance
`dataType`	`string`	`'html'`	Data type of AJAX request
`headers`	`object`		An object of additional header key/value pairs to send along with requests
`label`	`string`	`'Drag and drop files or click to select'`	Drop target text; `false` to disable
`leave`	`string`	`'You have uploads pending, are you sure you want to leave this page?'`	Before leave message
`maxConcurrent`	`int`	`2`	Number of files to simultaneously upload
`maxFiles`	`int OR boolean`	`false`	Total number of files that can be uploaded; `false` to disable
`maxSize`	`int`	`5242880`	Max file size allowed
`multiple`	`true`	`true`	Flag to allow mutiple file uploads
`postData`	`object`		Extra data to post with upload
`postKey`	`string`	`'file'`	Key to upload file as
`theme`	`string`	`"fs-light"`	Theme class name

Events

Events are triggered on the target instance's element, unless otherwise stated.

Event	Description
`chunkcomplete`	File chunk complete
`chunkstart`	File chunk starting
`chunkerror`	File chunk error
`complete`	All uploads are complete
`filecomplete`	Specific upload complete
`filedragenter`	File dragged into target
`filedragleave`	File dragged from target
`filedragover`	File dragged over target
`fileerror`	Specific upload error
`fileprogress`	Specific upload progress
`filestart`	Specific upload starting
`fileremove`	Specific upload removed
`start`	Uploads starting
`queued`	Files are queued for upload

Methods

Methods are publicly available to all active instances, unless otherwise stated.

abort

Cancels all active uploads, or specific file.

$(".target").upload("abort", [index]);

defaults

Extends plugin default settings; effects instances created hereafter.

$.upload("defaults", { ... });

Parameters

Name	Type	Default	Description
`options`	`object`	`{}`	New plugin defaults

destroy

Removes plugin instance.

$(".target").upload("destroy");

disable

Disables target instance.

$(".target").upload("disable");

enable

Enables target instance.

$(".target").upload("enable");

start

Starts queued uploads; Use when autoUpload is set to false.

$(".target").upload("start");

CSS

Class	Type	Description
`.fs-upload-element`	`element`	Target elmement
`.fs-upload`	`element`	Base widget class
`.fs-upload.fs-upload-dropping`	`modifier`	Indicates dropping state
`.fs-upload.fs-upload-disabled`	`modifier`	Indicates disabled state
`.fs-upload-input`	`element`	Masked Input
`.fs-upload-target`	`element`	Drop target