www.aleph1.co.uk Git - yaffs-website/blob - vendor/enyo/dropzone/README.md

   1 <img alt="Dropzone.js" src="http://www.dropzonejs.com/images/new-logo.svg" />
   2
   3 [ ![Codeship Status for enyo/dropzone](https://codeship.com/projects/3fc90800-74e0-0132-38ce-22ab3bab314c/status?branch=master)](https://codeship.com/projects/55087)
   4
   5 Dropzone.js is a light weight JavaScript library that turns an HTML element into a dropzone.
   6 This means that a user can drag and drop a file onto it, and the file gets uploaded to the server via AJAX.
   7
   8 * * *
   9
  10 _If you want support, please use [stackoverflow](http://stackoverflow.com/) with the `dropzone.js` tag and not the
  11 GitHub issues tracker. Only post an issue here if you think you discovered a bug or have a feature request._
  12
  13 * * *
  14
  15 **Please read the [contributing guidelines](CONTRIBUTING.md) before you start working on Dropzone!**
  16
  17 <br>
  18 <div align="center">
  19   <a href="https://github.com/enyo/dropzone/releases/latest"><strong>&gt;&gt; Download &lt;&lt;</strong></a>
  20 </div>
  21 <br>
  22 <br>
  23
  24
  25 Starting with version 2.0.0 this library does no longer depend on jQuery (but
  26 it still works as a jQuery module).
  27
  28 Dropzone is compatible with [component](https://github.com/component/component),
  29 there's a standalone version and an [AMD](https://github.com/amdjs/amdjs-api/wiki/AMD)
  30 module that's compatible with [RequireJS](http://requirejs.org) in the downloads
  31 folder.
  32
  33 <img slt="Dropzone Screenshot" width="585" src="http://i.imgur.com/Xf7QvVG.png" />
  34
  35
  36
  37 ## Main features
  38
  39 - Image thumbnail previews. Simply register the callback `thumbnail(file, data)` and display the image wherever you like
  40 - Retina enabled
  41 - Multiple files and synchronous uploads
  42 - Progress updates
  43 - Support for large files
  44 - Complete theming. The look and feel of Dropzone is just the default theme. You
  45   can define everything yourself by overwriting the default event listeners.
  46 - Well tested
  47
  48 ## Documentation
  49
  50 For the full documentation and installation please visit www.dropzonejs.com
  51
  52 Please also refer to the [FAQ](https://github.com/enyo/dropzone/wiki/FAQ).
  53
  54 ## Examples
  55
  56 For examples, please see the [GitHub wiki](https://github.com/enyo/dropzone/wiki).
  57
  58 ## Usage
  59
  60 Implicit creation:
  61
  62 ```html
  63 <form id="my-awesome-dropzone" action="/target" class="dropzone"></form>
  64 ```
  65
  66 That's it. Really!
  67
  68 Dropzone will automatically attach to it, and handle file drops.
  69
  70 Want more control? You can configure dropzones like this:
  71
  72 ```js
  73 // "myAwesomeDropzone" is the camelized version of the ID of your HTML element
  74 Dropzone.options.myAwesomeDropzone = { maxFilesize: 1 };
  75 ```
  76
  77 ...or instantiate dropzone manually like this:
  78
  79 ```js
  80 new Dropzone("div#my-dropzone", { /* options */ });
  81 ```
  82
  83 > Note that dropzones don't have to be forms. But if you choose another element you have to pass the `url` parameter in the options.
  84
  85 For configuration options please look at the [documentation on the website](http://www.dropzonejs.com/#configuration)
  86 or at the [source](https://github.com/enyo/dropzone/blob/master/src/dropzone.coffee#L90).
  87
  88
  89
  90 ### Register for events
  91
  92 If you want to register to some event you can do so on the `dropzone` object itself:
  93
  94 ```js
  95 Dropzone.options.myDropzone({
  96   init: function() {
  97     this.on("error", function(file, message) { alert(message); });
  98   }
  99 });
 100 // or if you need to access a Dropzone somewhere else:
 101 var myDropzone = Dropzone.forElement("div#my-dropzone");
 102 myDropzone.on("error", function(file, message) { alert(message); });
 103 ```
 104
 105 For a list of all events, please look at the chapter
 106 [»Events«](http://www.dropzonejs.com/#events) in the documentation
 107 or at the [source](src/dropzone.coffee#L43).
 108
 109
 110 ## Browser support
 111
 112 - Chrome 7+
 113 - Firefox 4+
 114 - IE 10+
 115 - Opera 12+ (Version 12 for MacOS is disabled because their API is buggy)
 116 - Safari 6+
 117
 118 For all the other browsers, dropzone provides an oldschool file input fallback.
 119
 120 ## Why another library?
 121
 122 I realize that there [are](http://valums.com/ajax-upload/) [already](http://tutorialzine.com/2011/09/html5-file-upload-jquery-php/) [other](http://code.google.com/p/html5uploader/) [libraries](http://blueimp.github.com/jQuery-File-Upload/) out there but the reason I decided to write my own are the following:
 123
 124 - I didn't want it to be too big, and to cumbersome to dive into.
 125 - I want to design my own elements. I only want to register callbacks so I can update my elements accordingly.
 126 - Big files should get uploaded without a problem.
 127 - I wanted a callback for image previews, that don't kill the browser if too many too big images are viewed.
 128 - I want to use the latest API of browsers. I don't care if it falls back to the normal upload form if the browser is too old.
 129 - I don't think that it's necessary anymore to depend on libraries such as jQuery (especially when providing functionality that isn't available in old browsers anyway).
 130
 131 MIT License
 132 -----------
 133
 134 See LICENSE file