Installation

Just include jQuery and shDropUpload source files into the head tag.

<html>
  <head>
    ...
    <script src="http://code.jquery.com/jquery-2.0.3.min.js" type="text/javascript"></script>
    <script src="/your/path/to/jquery.shDropUpload-min.js" type="text/javascript"></script>
    ...
  </head>
  <body>
    ...
  </body>
</html>

Construct & Destruct

First you have to put a <div> tag with appropriate width and height at the right spot on the page.

<div id="upload" style="width: 200px; height: 200px; background: #ddd">Drop here!</div>

Next you have to call shDropUpload() plugin function applied to the created <div> tag with appropriate options.

$('#upload').shDropUpload({
    url: "/your/upload/script.php"
});

Later, you can disable drag and drop uploading, calling plugin function without arguments:

$('#upload').shDropUpload();

Options

There are two kinds of options.

$('#upload').shDropUpload(localOptions, remoteOptions);

localOptions - about drag and drop files from local file system.

remoteOptions - about drag and drop HTML objects from external web pages.

Both parameters should be objects and they are NOT required. If any of both parameters is false, null, 0, empty string or it is missing, the drag and drop functionality will be disabled. Examples:

Enable local drag and drop only:

$('#upload').shDropUpload({
    url: "/your/upload/script.php"
});

Enable remote drag and drop only:

$('#upload').shDropUpload(false, {
    ajax: {
        url: "/your/script.php"
    }
});

Enable both:

$('#upload').shDropUpload({
    url: "/your/upload/script.php"
}, {
    ajax: {
        url: "/your/script.php"
    }
});

Disable both:

$('#upload').shDropUpload();

Local Options

url [String] Default: ""

URL to upload handler script. Should output appropriately response for the event callback functions.

param [String] Default: "upload"

Name of the GET parameter used for file content.

maxFilesize [Integer] Default: 10485760

Maximum file size of every uploaded file in bytes. The reason this option exists is that browser crashes when bigger files are dropped. If you don't want any limit, set this option to zero.

precheck (event) Default return: true

Used to do some checks before uploading begins. The event parameter gives the drop event object. Function should return false to cancel the upload process.

begin (xhr, currentFile, filesCount)

Called before uploading of every file. Useful for updating a progress bar. xhr parameter gives the XMLHttpRequest object. currentFile gives the number of the current uploading file, filesCount - total number of uploading files. There is additional field in xhr parameter - file, which is File object about the current file.

success (xhr, currentFile, filesCount)

Called upon succesful upload of single file. The parameters are identical as the previous option.

error (xhr, currentFile, filesCount)

Called when single upload request fails. The xhr parameter may give ProgressEvent object upon FileReader error.

abort (xhr, currentFile, filesCount)

Called when single upload request is aborted.

filesizeCallback (xhr, currentFile, filesCount)

Called when single upload file size exceeds the defined in maxFileSize value.

finish ()

Called when all uploads are passed.

Remote Options

selectors [String] or [Array] Default: "img[src]"

Defines the tags and their attribute, the URLs will be fetched from.

unique [Boolean] Default: true

Whether to check URLs for uniqueness if a HTML selection is dropped.

ajax [Object]

Ajax options for the request. Click here for details. Default ajax options:

{
    url: "",
    type: "post",
    dataType: "json",
    data: {
        url: "{url}",
        type: "{type}"
    },
    success: function(response) {
        console.log("shDropUpload: URL has been passed to the server.");
    },
    error: function() {
        console.log("shDropUpload: Request failed!");
    },
    abort: function() {
        console.log("shDropUpload: Request aborted!");
    }
}

The data field gives the server request parameters. shDropUpload parses {url} and {type} values.

If there are multiple URLs from dropped object, {url} and {type} becomes arrays of strings, otherwise - strings.

{type} represents the HTML tag name(s) the URL is fetched from (e.g. img).

{url} represents the URL(s), fetched from HTML tags.