FileDrop.js ²

Preface

Project news by TextFeeder

Logos & buttons

If you like FileDrop you can spread the word with these cute image (feel free to hotlink; browse directory):

Icons of various dimensions: 16, 32, 64, 128
The same icons not optimized for web (if the above look broken in your editor): 16, 32, 64, 128

Download & License

FileDrop is released in public domain — feel free to use it however you like. However, a humble backlink to this site (filedropjs.org) will inspire the author to create even more useful libraries :)

First FileDrop release has been in January 2012.

Download FileDrop — includes demo page, minified (filedrop-min.js) and full (filedrop.js) JavaScript files. To use FileDrop you only need one of them.

FileDrop is hosted at GitHub — feel free to fork it, report bugs and otherwise contribute to the project.

Last v1 release is available at the separate branch named v1.

See also on-line demo page which speaks better than thousand words.

For development purposes you can hotlink to the script on GitHub:

https://raw.github.com/ProgerXP/FileDrop/master/filedrop.js
https://raw.github.com/ProgerXP/FileDrop/master/filedrop-min.js

Getting started

FileDrop works out of the box in any supported browser as long as its JavaScript is linked into your page. Additionally, if you want to use legacy upload for browsers not suporting drag & drop (these include IE and Opera) you need to include the following CSS (you can change it but be careful not to break things):

css/***
  Styles below are only required if you're using <iframe> fallback in
  addition to HTML5 drag & drop (only working in Firefox/Chrome/Opera 15+).
 ***/

/* Essential FileDrop zone element configuration: */
.fd-zone {
  position: relative;
  overflow: hidden;
  /* The following are not required but create a pretty box: */
  width: 15em;
  margin: 0 auto;
  text-align: center;
}

/* Hides <input type="file"> while simulating "Browse" button: */
.fd-file {
  opacity: 0;
  font-size: 118px;
  position: absolute;
  right: 0;
  top: 0;
  z-index: 1;
  padding: 0;
  margin: 0;
  cursor: pointer;
  filter: alpha(opacity=0);
  font-family: sans-serif;
}

/* Provides visible feedback when user drags a file over the drop zone: */
.fd-zone.over { border-color: maroon; background: #eee; }

Simplest, most basic usage example is available in the included demo page as basic.html.

Nat Dunn from Webucator has created a video on FileDrop basics:

Migrating from v1

10 times more the documentation. HTML5 more the support.

New FileDrop version is not a drop-in replacement for the old one. However, there are no changes that will require you rewriting the code completely… Server-side compatibility has been preserved so no migration is necessary in this area.

You are highly encouraged to use the new version since it contains all the features of the first one while adding new ones and fixing lots of bugs and compatibility issues.

Changelog

1. Changed names from UpperCamelCase to lowerCamelCase — e.g. SendTo became sendTo.
2. Added return values and checks to many utility methods making them less prone to unexpected argument types.
3. Removed semicolons.
4. Removed hardcoded references to window.fd, wrapped everything in closure. Now it’s easy to export this module or replace window.fd with something else of your liking.
5. Events were moved from on property to events (the former still exists but is deprecated). Added event() and preview() methods — an interface to un/binding FileDrop events (not DOM events).
6. Renamed zone property into el (old name is still accessible but deprecated).
7. jQuery plugin now adds $el property that requals to $(el): zone.$el.
8. Events can now have namespaces after a colon: event:namespace. See event() description for details.
9. Reformatted the code, removed extra indentation.
10. multiple() no more throws an exception if the object doesn’t use xml<iframe> upload (just does nothing).
11. SetClassesTo() was removed.
12. Added File’s xhrSetup event (occurs before sendXHR).
13. Renamed sendXHR event to xhrSend (old name is still accessible but deprecated).
14. Added type (MIME) and modDate (Date object) props to File.
15. Replaced native array object given to send event with FileList-like array-like object with some useful methods.
16. Added File.readData() and readDataURI() to read binary/data URL/text data of the underlying native File object.
17. Object-wise event preview was renamed from event to any.
18. fd.onObjCall() property renamed to onObjectCall.
19. Added dropEffect option for DropHandle.

Some functions have been renamed in addition to case change:

• fd.CallOf → callAllOfObject
• DropHandle.FindInputRec → findInputRecursive
• DropHandle.SetupInput → doInputSetup
• FileDrop.GetFilesFrom → eventFiles
• File.DoSendTo → sendDataReadyTo

Samples

The minimum

To create a drop zone you need to have a basic element — such as a fieldset. It’s typically marked up in HTML and then retrieved by ID as in the example below. In this example, if you select or drop a file nothing will happen yet.

// We can deal with iframe uploads using this URL:
var options = {iframe: {url: 'upload.php'}}
// 'zone' is an ID but you can also give a DOM node:
var zone = new FileDrop('zone', options)

// Do something when a user chooses or drops a file:
zone.event('send', function (files) {
  // FileList might contain multiple items.
  files.each(function (file) {
    // Send the file:
    file.sendTo('upload.php')
  })
})

<!-- A FileDrop area. Can contain any text or elements, or be empty.
     Can be of any HTML tag too, not necessary fieldset. -->
<fieldset id="zone">
  <legend>Drop a file inside...</legend>
  <p>Or click here to <em>Browse</em>...</p>
</fieldset>

Reacting to success

Let’s extend the first example with a simple on-done listener:

var options = {iframe: {url: 'upload.php'}}
var zone = new FileDrop('zone1', options)

zone.event('send', function (files) {
  files.each(function (file) {
    // React on successful AJAX upload:
    file.event('done', function (xhr) {
      // Here, 'this' points to fd.File instance.
      alert(xhr.responseText)
    })

    file.sendTo('upload.php')
  })
})

// Successful iframe upload uses separate mechanism
// from proper AJAX upload hence another listener:
zone.event('iframeDone', function (xhr) {
  alert(xhr.responseText)
})

<div id="zone1">
  <p class="legend">Drop a file inside...</p>
</div>

Passing custom data

When using both HTML5 and legacy uploads we can only rely on GET query variables — POST might be used to pass file data in one raw stream.

var zone = new FileDrop('zone2')

zone.event('send', function (files) {
  files.each(function (file) {
    file.event('done', function (xhr) {
      alert(xhr.responseText)
    })

    // byID() gets checkbox node by its ID:
    var value = fd.byID('upload_option').checked ? '1' : '0'
    // Change the receiving URL:
    file.sendTo('upload.php?upload_option=' + value)
  })
})

<!-- As you see we don't have to use a fieldset, any container will work: -->
<div id="zone2">
  <p class="legend">Drop a file inside...</p>
  <p>
    <input type="checkbox" id="upload_option">
    <label for="upload_option">Toggle me!</label>
  </p>
</div>

Error handling

Sometimes request might fail. Below example will handle AJAX errors. Legacy xml<iframe> upload doesn’t support error callbacks.

var zone = new FileDrop('zone3')

zone.event('send', function (files) {
  files.each(function (file) {
    // Listen for errors:
    file.event('error', function (e, xhr) {
      alert(xhr.status + ', ' + xhr.statusText)
    })

    file.sendTo('this-is-a-wrong-place-to-go.php')
  })
})

<div id="zone3">
  <p class="legend">Drop a file inside...</p>
</div>

Timeout reporting

Error event will be fired if server returns a non-200 response code or the AJAX request fails. Note that it won’t be fired by a timeout — you need so set it up yourself like this:

Note that it isn’t possible to catch errors of legacy xml<iframe> upload so the best way is to have a timeout timer that will be aborted if server response is received earlier than it triggers.

var zone = new FileDrop('zone4')

zone.event('send', function (files) {
  files.each(function (file) {
    file.event('error', function (e, xhr) {
      if (xhr.readyState == 4 && !xhr.status) {
        alert('Timeout reached, request aborted.')
      } else {
        alert(xhr.status + ', ' + xhr.statusText)
      }
    })

    setTimeout(function () {
      // Aborting a request changes XMLHttpRequest status to
      // "done but failed" and thus fires all registered error
      // callbacks. The same happens if user aborts upload
      // implicitly by navigating away or pressing Escape.
      file.abort()
    }, 3000)

    file.sendTo('wait-forever.php')
  })
})

<div id="zone4">
  <p class="legend">Drop a file inside...</p>
</div>

Aborting an upload

var zone = new FileDrop('zone5')

// FileList is a simple array-like object
// with many useful File-related methods:
var active = new fd.FileList

// Enabling multifile upload so you can
// test aborting several requests at once
// (one file is sent by its own XMLHttpRequest):
zone.multiple(true)

zone.event('send', function (files) {
  files.each(function (file) {
    file.event('done', function (xhr) {
      alert(xhr.responseText)
    })

    file.sendTo('wait-forever.php')
    active.push(file)
  })
})

// This is called when you click the button:
window.stopAll = function () {
  active.abort()
  alert('Aborted ' + active.length + ' upload(s).')
  active.clear()
}

<div id="zone5">
  <p class="legend">Drop a file inside...</p>
  <p><button onclick="stopAll()">Stop them!</button></p>
</div>

IFrame fallback

Legacy xml<iframe> fallback is necessary if you want to support non-File API browsers (all but Firefox and Chrome-based agents as of today).

var options = {iframe: {url: 'upload.php'}}
var zone = new FileDrop('zone6', options)

zone.event('send', function (files) {
  files.each(function (file) {
    file.event('done', function (xhr) {
      alert(xhr.responseText)
    })

    var value = fd.byID('zone6_option').checked ? '1' : '0'
    file.sendTo('upload.php?upload_option=' + value)
  })
})

// Update <iframe> URL when the checkbox is toggled:
fd.addEvent(fd.byID('zone6_option'), 'change', function () {
  var value = fd.byID('zone6_option').checked ? '1' : '0'
  zone.opt.iframe.url = 'upload.php?upload_option=' + value
})

<div id="zone6">
  <p class="legend">Drop a file inside...</p>
  <p>
    <input type="checkbox" id="zone6_option">
    <label for="zone6_option">Toggle me!</label>
  </p>
</div>

This sample is identical to that passing custom data except that upload.php was specified in iframe.url option and a listener was added to the checkbox to update upload URL when its state changes.

When user clicks the drop zone and selects one or more files in the Browse dialog FileDrop will upload them by submitting a form that’s automatically created inside the drop zone (but it doesn’t wrap its contents).

Query variables are passed differently depending on whether upload happens via xml<iframe> or not:

• if yes, all data is given as multipart/form-data POST.
• if no, file data is given as raw POST data and custom variables (like in the previous sample) are passed by GET.

Zone-wrapping form

In the above example we had to manually update the xml<iframe> URL. However, if there are many elements this can be troublesome. When creating a drop zone FileDrop will first check to see if it already contains a form that can be used for legacy upload. If it does — no extra elements will be created which means that we can wrap all our input fields into a form and when FileDrop automatically submits it to the server as a result of user selecting a file that request will come along with the relevant POST data.

For this we can simply copy FileDrpo’s HTML code when it creates a regular drop zone — using Firebug or other tool.

Note that we have added name attribute to the checkbox element.

var options = {iframe: {url: 'upload.php'}}
var zone = new FileDrop('zone7', options)

zone.event('send', function (files) {
  files.each(function (file) {
    file.event('done', function (xhr) {
      alert(xhr.responseText)
    })

    var value = fd.byID('zone7_option').checked ? '1' : '0'
    file.sendTo('upload.php?upload_option=' + value)
  })
})

<div id="zone7">
  <iframe name="wrapFrame" src="javascript:false"
          id="wrapFrame" style="display: none"></iframe>

  <form enctype="multipart/form-data" method="post" target="wrapFrame">
    <input type="hidden" name="fd-callback">
    <input type="file" name="fd-file" class="fd-file">

    <p>
      <input type="checkbox" id="zone7_option" name="zone7_option">
      <label for="zone7_option">Toggle me!</label>
    </p>
  </form>

  <p class="legend">Drop a file inside...</p>
</div>

Drop-only control

Sometimes you’d ditch IFrame support in favour of drag & drop goodness for Firefox and Chrome (and now Opera). For example, you have a large text area where a user can input text manually but also drop a file to be sent to the server via AJAX. This way you don’t need to create a hidden file input that, when clicked, will allow the user to select files to upload. The server can respond with some modified version of the original file that you will use to populate the area.

This is done by setting input option to false turning drop zone into pure HTML5 upload area. With this iframe options and events are no more working.

var options = {input: false}
var zone = new FileDrop('zone8', options)

zone.event('send', function (files) {
  files.each(function (file) {
    file.event('done', function (xhr) {
      zone.el.value = xhr.responseText
    })

    file.sendTo('upload.php')
  })
})

<textarea id="zone8">
Type something here or drag & drop a file from your computer.
</textarea>

Reading dropped data

We can enhance drag & drop onto custom control sample by avoiding server communication at all. Once we have obtained a fd.File object in FileDrop’s send event we can use its readXXX() methods to generate thumbnails or just read text or raw binary data.

readData() is heavily documented in the comments with many examples so check out the sources for the details. See also HTML5 File API samples below and sample thumb generator of the demo page.

var options = {input: false}
var zone = new FileDrop('zone9', options)

zone.event('send', function (files) {
  files.each(function (file) {
    file.readData(
      function (str) { zone.el.value = str },
      function (e) { alert('Terrible error!') },
      'text'
    )
  })
})

<textarea id="zone9" readonly="readonly">
Drag & drop a file here to view its contents.
</textarea>

Progress bar

File’s progress event lets you easily track large file uploads if it’s supported by the browser. In Firefox this event only works on big files.

var zone = new FileDrop('zone10')

zone.event('send', function (files) {
  files.each(function (file) {
    // Reset the progress when a new upload starts:
    file.event('sendXHR', function () {
      fd.byID('bar_zone10').style.width = 0
    })

    // Update progress when browser reports it:
    file.event('progress', function (current, total) {
      var width = current / total * 100 + '%'
      fd.byID('bar_zone10').style.width = width
    })

    file.sendTo('upload.php')
  })
})

<div id="zone10">
  <p class="legend">
    Drop a large file to see some progress...
  </p>

  <!-- You can also use <progress> tag of HTML5: -->
  <p class="progress">
    <span id="bar_zone10"></span>
  </p>
</div>

HTML5 File API

HTML5 specification finally allows us to find out some info about user-selected files before they’re submitted to the server and it even les us read their data. FileDrop simplifies and uniformizes this access across different borwsers.

If you have a file input that you want to read files from the following code will create a collection of normalized fd.File objects and use their properties to show file info:

var zone = new FileDrop('zone11')
zone.multiple(true)

// opt.input contains file input created by FileDrop:
zone.opt.input.file.onchange = function (e) {
  // eventFiles() retrieve dropped File objects in
  // a cross-browser fashion:
  zone.eventFiles(e).each(function (file) {
    alert(file.name + ' (' + file.size + ') bytes')
  })
}

<div id="zone11">
  <p class="legend">Click here to browse for files...</p>
</div>

Pure HTML5 drop zone

The previous example with file input and onchange is a bit oldschool. We can use HTML5 drag & drop events to catch dropped files without having to select them in a file dialog. We listen to send event just like usual but disable file input creation on this drop zone to be «completely HTML5» (no support for older browsers).

Note that files given to send is of the same type as that we obtain from eventFiles() in the example above — FileList collection.

If we leave input option enabled browsers like earlier Opera will trigger onchange event and upload the file via xml<iframe> instead of letting us read file information on drop.

var zone = new FileDrop('zone12', {input: false})

zone.event('send', function (files) {
  files.each(function (file) {
    alert(file.name + ' (' + file.size + ') bytes')
  })
})

<div id="zone12">
  <p class="legend">Drop some files here...</p>
</div>

Generating thumbnails

This is among the coolest tasks — uploading photos. FileDrop makes it easy to generate thumbnails prior to sending files to the server — just when they were dropped onto your drop zone. It requires HTML5 File API support and won’t work on fallback xml<iframe> uploads. See also on-line demo page with a similar example.

var zone = new FileDrop('zone13', {input: false})

zone.event('send', function (files) {
  // images() filter away all but image/* files:
  files.images().each(function (file) {
    file.readData(
      function (uri) {
        var img = new Image
        img.src = uri
        alert('Got an ' + file.type)    // e.g. image/jpeg.
        zone.el.appendChild(img)
      },
      function (error) {
        alert('Ph, noes! Cannot read your image.')
      },
      'uri'
    )
  })
})

<div id="zone13">
  <p class="legend">Drop some files here...</p>
</div>

Last parameter to readData() specifies the form of argument that will be passed to the first callback. For thumbs (value of xml<img src="...">) we can pass uri, url or src — all of which are aliases to readAsDataURL.

Instead of the above readData() call we could also use either this alias:

jsfile.readDataURI(
  function (uri) {
    // as above: img.src = url
  },
  function (error) {
    // as above.
  }
)

Or event this if we don’t need error handling:

jsfile.readDataURI(function (uri) {
  // as above: img.src = url
})

Partial reading — Blob slices

Another nice feature of HTML5 File API is that it allows us processing really big files with no real limit. We can read file from arbitrary offset with arbitrary length and even specify a Content-Type for the new chunk. We can treat this chunk as Data URI, text or binary data just like entire file.

FileDrop lets you read slices and handle errors using a single function — read(). readData() and readDataURI() that we’ve seen above are shortcuts much like jQuery.getJSON() and jQuery.ajax()).

var zone = new FileDrop('zone14', {input: false})

zone.event('send', function (files) {
  files.each(function (file) {
    file.read({
      start: 5,
      end: -10,
      func: 'cp1251',
      onDone: function (str) {
        alert('A snippet from your CP1251-encoded file:\n' + str)
      },
      onError: function (e) {
        alert('Failed to read the file! Error: ' + e.fdError)
      }
    })
  })
})

<div id="zone14">
  <p class="legend">Drop a text file here...</p>
</div>

This example will display file contents starting with 5^th byte and ending on 11^th byte from the end (end doesn’t include given offset) treated as a string in CP1251 encoding. These options can be combined in different ways to achieve desired effect. Here’s another idea:

jsfile.read({
  // Read first 4 bytes (start defaults to 0).
  end: 5,
  // Mark them as a picture.
  mime: 'image/jpeg',
  // Read as a Data URI for our thumb <img>.
  func: 'uri',
  onDone: function (uri) {
    // We've defined no onError handler so read() will call onDone passing error
    // object with custom fdError property as the first argument.
    if (typeof bytes == 'object') {
      alert('Problem: ' + bytes.fdError)
    } else {
      fd.byID('myImg').src = uri
    }
  }
})

Reading directories

W3C has a working draft on File System API that introduces lots of interesting features allowing us to read and write files and directories (currently supported only in Chrome 21+). FileDrop lets you use its FileList and File methods to list folders, upload files, read file data (full or partial) and so on.

var zone = new FileDrop('zone15', {input: false})

zone.event('upload', function (e) {
  zone.eventFiles(e).each(function (root) {
    var ok = root.listEntries(
      function (files) {
        // We now have standard FIleDrop's FileList with File
        // members that are either files or directories.
        files.images().each(function (file) {
          // Just as in the other sample...
          file.readDataURI(function (uri) {
            var img = new Image
            img.src = uri
            zone.el.appendChild(img)
          })
        })
      },
      function (e) {
        alert('Problem reading the file system: ' + e.code)
      }
    )

    ok || alert('Cannot list ' + root.name + ' - unsupported?')
  })
})

<div id="zone15">
  <p class="legend">Drop a directory with images here...</p>
</div>

jQuery integration

FileDrop can be integrated with jQuery by simply calling the following method (once, after loading both FileDrop and jQuery): jsfd.jQuery().

Drop zone events are prefixed with fd while individual file events start with file. DOM node events are triggered before those assigned to obj.on.XXX arrays and if a node handler returns non-null value on’s events are skipped.

Note that jQuery will prepend its own event object in front of FileDrop’s normal event arguments since they’re triggered as regular events of a DOM node. See extensive comments in the sources for more details and examples.

More information in the corresponding section.

jsfd.jQuery()  // you can also pass an object like 'jQuery' or '$'.

// Henceforth it's possible to access FileDrop as $().filedrop().
$('<div><p>Drop something here...</p></div>')
  .appendTo(document.body)
  .filedrop()
  // jQuery always passes event object as the first argument.
  .on('fdsend', function (e, files) {
    files.invoke('sendTo', 'upload.php')
  })
  .on('filedone', function (e, file) {
    alert('Done uploading ' + file.name + ' on ' + this.tagName)
  })

FileList

New FileDrop provides special FileList object instead of arrays that were used when passing dropped files to event listeners. This object is array-like and contains useful methods for filtering, sorting and updating the collection. Below are some examples — look in the docs and sources for complete info.

jszone.event('send', function (files) {
  alert('Dropped files: ' + files.length + '\n' +
        'First file: ' + files.first().name + '\n' +
        'File recently changed: ' + files.newest().name + '\n' +
        'Biggest file: ' + files.largest().name + '\n' +
        'Number of images: ' + files.images().length + '\n' +
        'Files starting with "A": ' + files.named(/^a/i).length)

  files.sortBy(function (f) { return f.size })
  files.reverse()
})

Documentation

All FileDrop implementation is contained within window.fd object. This object includes global options, utility functions and classes (mainly FileDrop itself). window.fd can be defined before including the script (filedrop.js or filedrop-min.js) — useful if you need to override certain options before FileDrop is loaded.

For example:

xml<script type="text/javascript">
  window.fd = {logging: false};
</script>

<script type="text/javascript" src="filedrop.js"></script>

FileDrop makes extensive use of events and lets you customize virtually every aspect of the drag & drop or upload process by intercepting and overriding default handlers.

Global options

Global options are set in window.fd:

Global functions

Below is a brief description of all functions placed into window.fd. Find examples and up-to-date information in the extensively commented source code.

Function signatures with zero or one arguments are omitted for brevity.

DropHandle class

Has some file upload functionality (mostly legacy xml<iframe>) but is mainly used to handle all drag & drop operations in a cross-browser way. You can use it as a basis for your own component. Main FileDrop class extends it and listens for produced drop events.

Constructor:

jsnew fd.DropHandle(zone, opt);
// Example:
new fd.DropHandle(document.body, {zoneClass: 'with-filedrop'});

zone — ID or DOM element which accepts drag & drop. This is often a xml<fieldset>. If such element doesn’t exist an exception is thrown when trying to create the class. DropHandle will add some children to this element to facilitate external drop events. Once created this element is accessible as js(new DropHandle(...)).el property.

opt — object, key/value pairs of options. See the code for the list of keys and their purpose. Can be omitted or empty to use defaults. Current option values are accessible as the opt property.

Properties

Options

IFrame options for fallback upload for browsers lacking native drag & drop support — IE and others:

Events

For the explanation of event handling see Samples, demo page and source code comments.

Methods

Below is a brief description of all methods available on a DropHandle instance. Find examples and up-to-date information in the extensively commented source code.

Function signatures with zero or one arguments are omitted for brevity.

Some low-level internal methods:

FileDrop class

Based on DropHandle to abstract from browser-specific drag & drop and fallback xml<iframe> upload quirks, this class adds actual upload functionality. It listens for drop events and xml<iframe> submission triggering dedicated events with normalized parameters. Underlying DropHandle class can be accessed via this.handle property. It shares options and events with FileDrop object so changing one affects another.

DropHandle properties and methods are available on this object as well.

This object is defined in window.fd and aliased as window.FileDrop.

Constructor:

jsnew FileDrop(zone, opt);
// Example:
new FileDrop(document.body, {zoneClass: 'with-filedrop'});

Parameters are identical to those of DropHandle.

Options

See also those inherited from DropHandle.

Properties

See also those inherited from DropHandle.

Events

See also those inherited from DropHandle.

Methods

Find examples and up-to-date information in the extensively commented source code.

See also those inherited from DropHandle.

FileList class

It’s sort of W3C class (that has no special methods defined in the spec) with a bunch of File-oriented methods that this object is meant to contain. It’s an array-like object with length, splice() and other methods.

Constructor:

jsnew fd.FileList(event);

event is native event object given by the browser in reply to onchange or ondrop events.

Properties

Methods

Below is a brief description of all methods available on a FileList instance. Find examples and up-to-date information in the extensively commented source code.

Function signatures with zero or one arguments are omitted for brevity.

File class

It’s passed on FileDrop send event as members of fd.FileList and provides cross-browser access to file information and ability to upload it to the server. Wraps around native browser’s File object.

Constructor:

jsnew fd.File(file);

file is native browser File object according to W3C specification that can be retrieved from the on-drop event object. Can be accessed via this.nativeFile property.

Properties

Options

Values here specify default values for sendTo() options — like HTTP method used to submit the data. They can be overriden by passing an object to sendTo() — e.g. jssendTo('upload.php', {method: 'PUT'}).

Events

For the explanation of event handling see Samples, demo page and source code comments.

Methods

Below is a brief description of all methods available on a File instance. Find examples and up-to-date information in the extensively commented source code.

Function signatures with zero or one arguments are omitted for brevity.

Some low-level internal methods:

jQuery interface

After both FileDrop and jQuery (v1 or v2) scripts have loaded call fd.jQuery(). Don’t forget to include/write your FileDrop’s CSS as well if you’re using xml<iframe>.

Once done it becomes possible to access FileDrop as js$('#zone').filedrop() and avoid accessing its methods and bind event altogether. FileDrop will trigger events as if they originated from the zone’s DOM node itself and prefix each event with either fd (DropHandle/FileDrop classes) or file (File class). For example, dragEnter becomes fd.dragenter. Arguments remain the same except that:

• jQuery always passes event object as the first argument so just skip it.
• File events (file prefix) get passed File object as second argument (after jQuery event) to let you know which instance they belong to.

Note that this points to jQuery collection and no more to the FileDrop or File instance that has initiated the event.

js$('<div><p>Drop something here...</p></div>')
  .appendTo(document.body)
  .filedrop()
  .on('fdsend', function (e, files) {
    // Occurs when FileDrop's 'send' event is initiated.
    $.each(files, function (i, file) {
      file.sendTo('upload.php')
    })
  })
  .on('filedone', function (e, file) {
    // Occurs when a File object has done uploading.
    alert('Done uploading ' + file.name + ' on ' + this.tagName)
  })

When constructing FileDrop instance by jQuery in addition to regular el property $el is set to point to $(el) — zone node wrapped as jQuery collection.

Also, it’s still possible to attach listeners to FileDrop object with jsfd.event('event', func) but these events are called after corresponding DOM events (added with jQuery). If a DOM event handler returns a non-null and non-undefined value then FileDrop’s handlers won’t be called.

Event preview handlers (any event) can only be attached directly to FileDrop:

js$('#zone')
  .fildrop()
  .filedrop().event('any', function () { ... })

You can access underlying FileDrop object by calling filedrop() without parameters (first such call creates FileDrop, later calls return the instance on the first element in the collection):

js$('#zone')            // select <p id="zone">
  .filedrop()         // turn it into a FileDrop zone
  .css({color: red})  // any normal jQuery code
  .filedrop()         // retrieve FileDrop object
  .multiple(true)     // call its method

Alternatively you can pass a string to filedrop() to select a property or call a method — in this case their value/result is returned:

js$('#zone')
  .filedrop()
  .filedrop('multiple', true)
    // returns the new state of 'multiple' option, not jQuery object.

It’s also possible to pass custom options to FileDrop constructor:

js$('#zone')
  .filedrop({
    multiple: true,
    iframe: {url: '/upload.php'}
  })

Legacy Docs (v1)

An entire FileDrop facility is contained in window.fd. In itself, FileDrop in itself is split into 2 classes: DropHandle and FileDrop, plus one File class. Apart from these there are global options and functions (belonging to window.fd instead of a particular FileDrop class).

FileDrop uses event-driven approach for better flexibility. See also CallOf() and CallAll() functions that call event chains (sets of callbacks).

Documentation in this section describes previous FileDrop version. General code structure has been precerved with the new edition but this section may refer to events and functions that have been changed or removed. See Changelog for more details or the latest docs section.

Last v1 release of FileDrop is available at the separate branch named v1.

Global options

Global options are set in window.fd:

Global functions

DropHandle class

This is an abstraction layer that provides FileDrop class with normalized events occurring on file Drag & Drop and Browse. It creates xml<input type="file"> and xml<iframe> elements and handlers their activity.

DropHandle doesn’t do anything except handling node events — it doesn’t change the appearence of zone or respond to Browse or Drag & Drop, it only invokes corresponding event handlers.

Constructor:

js// zone - a DOM element or ID to hook file upload events for.
// opt - optional options, see below.
new fd.DropHandle(zone, opt);

Options:

Note: you can access passed zone element using zone property of the DropHandle class.

Events

Events are stored in on property, e.g. jsaDropHandle.on[dragEnter]. Each on member is an array of callbacks.

Drag & Drop

All handlers are of form jsfunction (e) where e is the native browser event object. Most useful events are dragEnter and dragLeave because others either don’t work, are unstable or unclear.

For a detailed description of HTML 5 Drag & Drop events see this MozDev page.

Methods

Only methods of interest are listed here, others are easy to determine from the code.

FileDrop class

This class provides the actual FileDrop features. It’s based on DropHandle that gives a good degree of cross-browser abstraction. FileDrop uses DropHandle’s events to respond to user actions and as such provides the same callbacks as that class.

Also, all DropHandle options, methods and other fields exist in FileDrop as well.

Constructor:

js// zone - a DOM element or ID to hook file upload events for.
// opt - optional options, see below.
new fd.FileDrop(zone, opt);
// a global (window[]) alias exists - you should use it instead:
new FileDrop(zone, opt);

Options (see also DropHandle options):

Note: you can access DropHandle object by handle property of the FileDrop class.

Events

Events are stored in on property, e.g. jsaFileDrop.on[send]. Each on member is an array of callbacks.

Methods

Only methods of interest are listed here, others are easy to determine from the code.

File class

Browser-independent abstraction layer for dealing with File objects of supported browsers (currenly Firefox/, Chrome and Safari). Wraps around native browser File// object that it’s passed in the constructor.

It also provides a number of events wrapping around XMLHttpRequest (see SendTo() method).

Constructor:

js// file - a native File object returned by the browser from an event object.
new fd.File(file);

File class has one option:

File class has the following properties:

Events

Events are stored in on property, e.g. jsaFile.on[error]. Each on member is an array of callbacks.

Methods

Only methods of interest are listed here, others are easy to determine from the code.

End of documentation. Live Demo • Download • GitHub • Top ↑